freebsd-dev/lib/libc/net/gai_strerror.3
Pedro F. Giffuni 09ed804717 gai_strerror() - Update string error messages according to RFC 3493.
Error messages in gai_strerror(3) vary largely among OSs.

For new software we largely replaced the obsoleted EAI_NONAME and
with EAI_NODATA but we never updated the corresponding message to better
match the intended use. We also have references to ai_flags and ai_family
which are not very descriptive for non-developer end users.

Bring new new error messages based on informational RFC 3493, which has
obsoleted RFC 2553, and make them consistent among the header adn
manpage.

MFC after:	1 month
Differentical Revision:	D18630
2018-12-23 18:15:48 +00:00

90 lines
2.5 KiB
Groff

.\" $KAME: gai_strerror.3,v 1.1 2005/01/05 03:04:47 itojun Exp $
.\" $OpenBSD: gai_strerror.3,v 1.4 2004/12/20 23:04:53 millert Exp $
.\"
.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
.\" $FreeBSD$
.\"
.Dd December 23, 2018
.Dt GAI_STRERROR 3
.Os
.Sh NAME
.Nm gai_strerror
.Nd get error message string from EAI_xxx error code
.Sh SYNOPSIS
.In sys/types.h
.In sys/socket.h
.In netdb.h
.Ft "const char *"
.Fn gai_strerror "int ecode"
.Sh DESCRIPTION
The
.Fn gai_strerror
function returns an error message string corresponding to the error code
returned by
.Xr getaddrinfo 3
or
.Xr getnameinfo 3 .
.Pp
The following error codes and their meaning are defined in
.In netdb.h :
.Pp
.Bl -tag -width ".Dv EAI_BADFLAGS" -offset indent -compact
.It Dv EAI_AGAIN
Name could not be resolved at this time
.It Dv EAI_BADFLAGS
flags parameter had an invalid value
.It Dv EAI_BADHINTS
invalid value for
.Fa hints
.It Dv EAI_FAIL
Non-recoverable failure in name resolution
.It Dv EAI_FAMILY
Address family was not recognized
.It Dv EAI_MEMORY
Memory allocation failure
.It Dv EAI_NONAME
Name does not resolve
.It Dv EAI_OVERFLOW
argument buffer overflow
.It Dv EAI_PROTOCOL
Resolved protocol is unknown
.It Dv EAI_SERVICE
Service was not recognized for socket type
.It Dv EAI_SOCKTYPE
Intended socket type was not recognized
.It Dv EAI_SYSTEM
System error returned in
.Va errno
.El
.Sh RETURN VALUES
The
.Fn gai_strerror
function
returns a pointer to the error message string corresponding to
.Fa ecode .
If
.Fa ecode
is out of range, an implementation-specific error message string is returned.
.Sh SEE ALSO
.Xr getaddrinfo 3 ,
.Xr getnameinfo 3
.Sh STANDARDS
.Bl -tag -width ".It RFC 2743"
.It RFC 3493
Basic Socket Interface Extensions for IPv6
.El