diff options
| author | itojun <itojun@NetBSD.org> | 2005-01-11 07:26:57 +0000 |
|---|---|---|
| committer | itojun <itojun@NetBSD.org> | 2005-01-11 07:26:57 +0000 |
| commit | f6b6f2cd66ac2bcd67d53ef236b2cb4d5272da2d (patch) | |
| tree | d439dd16a24de03df7a6e55ab312b937f97725a9 | |
| parent | 554ce4f360b2d4f53e6c2ee6def6d7bfa89ff60f (diff) | |
written-from-scratch manpage (fixes ISOC copyright violation)
| -rw-r--r-- | lib/libc/net/gai_strerror.3 | 94 | ||||
| -rw-r--r-- | lib/libc/net/getnameinfo.3 | 352 |
2 files changed, 231 insertions, 215 deletions
diff --git a/lib/libc/net/gai_strerror.3 b/lib/libc/net/gai_strerror.3 new file mode 100644 index 00000000000..d21abf1d255 --- /dev/null +++ b/lib/libc/net/gai_strerror.3 @@ -0,0 +1,94 @@ +.\" $NetBSD: gai_strerror.3,v 1.1 2005/01/11 07:26:57 itojun Exp $ +.\" $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. +.\" +.Dd December 20, 2004 +.Dt GAI_STRERROR 3 +.Os +.Sh NAME +.Nm gai_strerror +.Nd get error message string from EAI_xxx error code +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/socket.h> +.Fd #include <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 +.Aq Pa netdb.h : +.Pp +.Bl -tag -width "EAI_ADDRFAMILYXX" -offset indent -compact +.It Dv EAI_ADDRFAMILY +address family for +.Fa hostname +not supported +.It Dv EAI_AGAIN +temporary failure in name resolution +.It Dv EAI_BADFLAGS +invalid value for +.Fa ai_flags +.It Dv EAI_BADHINTS +invalid value for +.Fa hints +.It Dv EAI_FAIL +non-recoverable failure in name resolution +.It Dv EAI_FAMILY +.Fa ai_family +not supported. +.It Dv EAI_MEMORY +memory allocation failure +.It Dv EAI_NODATA +no address associated with +.Fa hostname +.It Dv EAI_NONAME +.Fa hostname +or +.Fa servname +not provided, or not known +.It Dv EAI_PROTOCOL +resolved protocol is unknown +.It Dv EAI_SERVICE +.Fa servname +not supported for +.Fa ai_socktype +.It Dv EAI_SOCKTYPE +.Fa ai_socktype +not supported +.It Dv EAI_SYSTEM +system error returned in +.Va errno +.El +.Sh RETURN VALUES +.Fn gai_strerror +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 diff --git a/lib/libc/net/getnameinfo.3 b/lib/libc/net/getnameinfo.3 index 9a466e3a6ad..a9cb64a9100 100644 --- a/lib/libc/net/getnameinfo.3 +++ b/lib/libc/net/getnameinfo.3 @@ -1,258 +1,174 @@ -.\" $NetBSD: getnameinfo.3,v 1.32 2004/12/20 18:30:26 christos Exp $ -.\" $KAME: getnameinfo.3,v 1.27 2003/04/30 06:06:42 itojun Exp $ +.\" $NetBSD: getnameinfo.3,v 1.33 2005/01/11 07:26:57 itojun Exp $ +.\" $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $ +.\" $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc Exp $ .\" -.\" Copyright (c) 1983, 1987, 1991, 1993 -.\" The Regents of the University of California. All rights reserved. +.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. +.\" 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. .\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. +.\" 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. .\" -.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 -.\" -.Dd August 28, 2003 +.Dd December 20, 2004 .Dt GETNAMEINFO 3 .Os -.\" .Sh NAME .Nm getnameinfo -.Nd address-to-nodename translation in protocol-independent manner -.\" -.Sh LIBRARY -.Lb libc -.\" +.Nd socket address structure to hostname and service name .Sh SYNOPSIS -.In netdb.h +.Fd #include <sys/types.h> +.Fd #include <sys/socket.h> +.Fd #include <netdb.h> .Ft int -.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \ -"char *host" "socklen_t hostlen" "char *serv" "socklen_t servlen" \ -"int flags" -.\" +.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" "char *host" \ + "size_t hostlen" "char *serv" "size_t servlen" "int flags" .Sh DESCRIPTION The .Fn getnameinfo -function is defined for protocol-independent address-to-nodename translation. -Its functionality is a reverse conversion of -.Xr getaddrinfo 3 , -and implements similar functionality to +function is used to convert a +.Li sockaddr +structure to a pair of host name and service strings. +It is a replacement for and provides more flexibility than the .Xr gethostbyaddr 3 and .Xr getservbyport 3 -in a more sophisticated manner. -.Pp -This function looks up an IP address and port number provided by the -caller in the DNS and system-specific database, and returns text -strings for both in buffers provided by the caller. -The function indicates successful completion by a zero return value; -a non-zero return value indicates failure. +functions and is the converse of the +.Xr getaddrinfo 3 +function. .Pp -The first argument, -.Fa sa , -points to either a -.Li sockaddr_in -structure (for IPv4) or a -.Li sockaddr_in6 -structure (for IPv6) that holds the IP address and port number. The -.Fa salen -argument gives the length of the +.Li sockaddr +structure +.Fa sa +should point to either a .Li sockaddr_in or .Li sockaddr_in6 -structure. +structure (for IPv4 or IPv6 respectively) that is +.Fa salen +bytes long. .Pp -The function returns the nodename associated with the IP address in -the buffer pointed to by the +The host and service names associated with +.Fa sa +are stored in .Fa host -argument. -The caller provides the size of this buffer via the +and +.Fa serv +which have length parameters .Fa hostlen -argument. -The service name associated with the port number is returned in the buffer -pointed to by -.Fa serv , -and the -.Fa servlen -argument gives the length of this buffer. -The caller specifies not to return either string by providing a zero -value for the +and +.Fa servlen . +The maximum value for .Fa hostlen -or +is +.Dv NI_MAXHOST +and +the maximum value for .Fa servlen -arguments. -Otherwise, the caller must provide buffers large enough to hold the -nodename and the service name, including the terminating null characters. -.Pp -Unfortunately most systems do not provide constants that specify the -maximum size of either a fully-qualified domain name or a service name. -Therefore to aid the application in allocating buffers for these two -returned strings the following constants are defined in -.Aq Pa netdb.h : -.Bd -literal -offset -#define NI_MAXHOST 1025 -#define NI_MAXSERV 32 -.Ed -.Pp -The first value is actually defined as the constant -.Dv MAXDNAME -in recent versions of BIND's -.Aq Pa arpa/nameser.h -header -.Po -older versions of BIND define this constant to be 256 -.Pc -and the second is a guess based on the services listed in the current -Assigned Numbers RFC. -.Pp -The final argument is a -.Fa flag -that changes the default actions of this function. -By default the fully-qualified domain name (FQDN) for the host is -looked up in the DNS and returned. -If the flag bit -.Dv NI_NOFQDN -is set, only the nodename portion of the FQDN is returned for local hosts. -.Pp -If the -.Fa flag -bit -.Dv NI_NUMERICHOST -is set, or if the host's name cannot be located in the DNS, -the numeric form of the host's address is returned instead of its name -.Po -e.g., by calling -.Fn inet_ntop -instead of -.Fn gethostbyaddr -.Pc . -If the -.Fa flag -bit -.Dv NI_NAMEREQD -is set, an error is returned if the host's name cannot be located in the DNS. -.Pp -If the flag bit -.Dv NI_NUMERICSERV -is set, the numeric form of the service address is returned -.Pq e.g., its port number -instead of its name. -The two -.Dv NI_NUMERICxxx -flags are required to support the -.Fl n -flag that many commands provide. +is +.Dv NI_MAXSERV , +as defined by +.Aq Pa netdb.h . +If a length parameter is zero, no string will be stored. +Otherwise, enough space must be provided to store the +host name or service string plus a byte for the NUL terminator. .Pp -A fifth flag bit, -.Dv NI_DGRAM , -specifies that the service is a datagram service, and causes -.Fn getservbyport +The +.Fa flags +argument is formed by +.Tn OR Ns 'ing +the following values: +.Bl -tag -width "NI_NUMERICHOSTXX" +.It Dv NI_NOFQDN +A fully qualified domain name is not required for local hosts. +The local part of the fully qualified domain name is returned instead. +.It Dv NI_NUMERICHOST +Return the address in numeric form, as if calling +.Xr inet_ntop 3 , +instead of a host name. +.It Dv NI_NAMEREQD +A name is required. +If the host name cannot be found in DNS and this flag is set, +a non-zero error code is returned. +If the host name is not found and the flag is not set, the +address is returned in numeric form. +.It NI_NUMERICSERV +The service name is returned as a digit string representing the port number. +.It NI_DGRAM +Specifies that the service being looked up is a datagram +service, and causes +.Xr getservbyport 3 to be called with a second argument of .Dq udp instead of its default of .Dq tcp . -This is required for the few ports (512-514) -that have different services for UDP and TCP. +This is required for the few ports (512\-514) that have different services +for +.Tn UDP +and +.Tn TCP . +.El .Pp -These -.Dv NI_xxx -flags are defined in -.Aq Pa netdb.h . -.\" -.Ss Extension for scoped IPv6 address -The implementation allows experimental numeric IPv6 address notation with -scope identifier. +This implementation allows numeric IPv6 address notation with scope identifier, +as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. IPv6 link-local address will appear as a string like .Dq Li fe80::1%ne0 . Refer to .Xr getaddrinfo 3 -for the notation. -.\" +for more information. +.Sh RETURN VALUES +.Fn getnameinfo +returns zero on success or one of the error codes listed in +.Xr gai_strerror 3 +if an error occurs. .Sh EXAMPLES -The following code tries to get a numeric hostname, and service name, -for given socket address. +The following code tries to get a numeric host name, and service name, +for a given socket address. Observe that there is no hardcoded reference to a particular address family. .Bd -literal -offset indent struct sockaddr *sa; /* input */ char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; -if (getnameinfo(sa, sa-\*[Gt]sa_len, hbuf, sizeof(hbuf), sbuf, +if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { errx(1, "could not get numeric hostname"); /*NOTREACHED*/ } -printf("host=%s, serv=%s\\n", hbuf, sbuf); +printf("host=%s, serv=%s\en", hbuf, sbuf); .Ed .Pp -The following version checks if the socket address has reverse address mapping. +The following version checks if the socket address has a reverse address mapping: .Bd -literal -offset indent struct sockaddr *sa; /* input */ char hbuf[NI_MAXHOST]; -if (getnameinfo(sa, sa-\*[Gt]sa_len, hbuf, sizeof(hbuf), NULL, 0, +if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, NI_NAMEREQD)) { errx(1, "could not resolve hostname"); /*NOTREACHED*/ } -printf("host=%s\\n", hbuf); +printf("host=%s\en", hbuf); .Ed -.\" -.Sh DIAGNOSTICS -The function indicates successful completion by a zero return value; -a non-zero return value indicates failure. -Error codes are as below: -.Bl -tag -width Er -.It Dv EAI_AGAIN -The name could not be resolved at this time. -Future attempts may succeed. -.It Dv EAI_BADFLAGS -The flags had an invalid value. -.It Dv EAI_FAIL -A non-recoverable error occurred. -.It Dv EAI_FAMILY -The address family was not recognized or the address length was invalid -for the specified family. -.It Dv EAI_MEMORY -There was a memory allocation failure. -.It Dv EAI_NONAME -The name does not resolve for the supplied parameters. -.Dv NI_NAMEREQD -is set and the host's name cannot be located, -or both nodename and servname were null. -.It Dv EAI_SYSTEM -A system error occurred. -The error code can be found in errno. -.El -.\" .Sh SEE ALSO +.Xr gai_strerror 3 , .Xr getaddrinfo 3 , .Xr gethostbyaddr 3 , .Xr getservbyport 3 , +.Xr inet_ntop 3 , +.Xr resolver 3 , .Xr hosts 5 , .Xr resolv.conf 5 , .Xr services 5 , .Xr hostname 7 , .Xr named 8 -.Pp .Rs .%A R. Gilligan .%A S. Thomson @@ -263,11 +179,14 @@ The error code can be found in errno. .%D March 1999 .Re .Rs -.%A Tatsuya Jinmei -.%A Atsushi Onoe -.%T "An Extension of Format for IPv6 Scoped Addresses" +.%A S. Deering +.%A B. Haberman +.%A T. Jinmei +.%A E. Nordmark +.%A B. Zill +.%T "IPv6 Scoped Address Architecture" .%R internet draft -.%N draft-ietf-ipngwg-scopedaddr-format-02.txt +.%N draft-ietf-ipv6-scoping-arch-02.txt .%O work in progress material .Re .Rs @@ -276,28 +195,24 @@ The error code can be found in errno. .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" .%D June 2000 .Re -.\" .Sh STANDARDS The .Fn getnameinfo -function is defined in IEEE POSIX 1003.1g draft specification, -and documented in -.Dq Basic Socket Interface Extensions for IPv6 -.Pq RFC 2553 . -.\" -.Sh HISTORY -The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. -.\" +function is defined by the +.St -p1003.1g-2000 +draft specification and documented in +.Tn "RFC 2553" , +.Dq Basic Socket Interface Extensions for IPv6 . .Sh CAVEATS .Fn getnameinfo -returns both numeric and FQDN notation of the address specified in +can return both numeric and FQDN forms of the address specified in .Fa sa . -There is no return value that indicates if the string returned in +There is no return value that indicates whether the string returned in .Fa host is a result of binary to numeric-text translation (like .Xr inet_ntop 3 ) , -or the result of DNS reverse lookup. -Therefore, malicious parties could set up a PTR record like below: +or is the result of a DNS reverse lookup. +Because of this, malicious parties could set up a PTR record as follows: .Bd -literal -offset indent 1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 .Ed @@ -308,13 +223,14 @@ into believing that .Fa sa is .Li 10.1.1.1 -when it actually is +when it is actually .Li 127.0.0.1 . .Pp To prevent such attacks, the use of .Dv NI_NAMEREQD -is recommended when you use the result of +is recommended when the result of .Fn getnameinfo +is used for access control purposes: .Bd -literal -offset indent struct sockaddr *sa; @@ -326,13 +242,13 @@ int error; error = getnameinfo(sa, salen, addr, sizeof(addr), NULL, 0, NI_NAMEREQD); if (error == 0) { - memset(\*[Am]hints, 0, sizeof(hints)); + memset(&hints, 0, sizeof(hints)); hints.ai_socktype = SOCK_DGRAM; /*dummy*/ hints.ai_flags = AI_NUMERICHOST; - if (getaddrinfo(addr, "0", \*[Am]hints, \*[Am]res) == 0) { + if (getaddrinfo(addr, "0", &hints, &res) == 0) { /* malicious PTR record */ freeaddrinfo(res); - printf("bogus PTR record\\n"); + printf("bogus PTR record\en"); return -1; } /* addr is FQDN as a result of PTR lookup */ @@ -342,8 +258,14 @@ if (error == 0) { NULL, 0, NI_NUMERICHOST); } .Ed -.\" .Sh BUGS -The current implementation is not thread-safe. -.Pp -The text was shamelessly copied from RFC 2553. +The implementation of +.Fn getnameinfo +is not thread-safe. +.\".Pp +.\".Ox +.\"intentionally uses a different +.\".Dv NI_MAXHOST +.\"value from what +.\".Tn "RFC 2553" +.\"suggests, to avoid buffer length handling mistakes. |
