diff options
Diffstat (limited to 'lib/libc/net')
| -rw-r--r-- | lib/libc/net/Makefile.inc | 16 | ||||
| -rw-r--r-- | lib/libc/net/gai_strerror.3 | 118 | ||||
| -rw-r--r-- | lib/libc/net/getaddrinfo.3 | 264 | ||||
| -rw-r--r-- | lib/libc/net/getnameinfo.3 | 105 |
4 files changed, 277 insertions, 226 deletions
diff --git a/lib/libc/net/Makefile.inc b/lib/libc/net/Makefile.inc index 8b34f57926b..79bfbb6b915 100644 --- a/lib/libc/net/Makefile.inc +++ b/lib/libc/net/Makefile.inc @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile.inc,v 1.34 2004/10/26 17:20:36 espie Exp $ +# $OpenBSD: Makefile.inc,v 1.35 2004/12/06 10:46:35 jmc Exp $ # net sources .PATH: ${LIBCSRCDIR}/arch/${MACHINE_ARCH}/net ${LIBCSRCDIR}/net @@ -28,12 +28,12 @@ SRCS+= ip6opt.c rthdr.c vars6.c .include "${LIBCSRCDIR}/arch/${MACHINE_ARCH}/net/Makefile.inc" -MAN+= byteorder.3 ethers.3 getaddrinfo.3 gethostbyname.3 getifaddrs.3 \ - getnameinfo.3 getnetent.3 getprotoent.3 getservent.3 inet.3 \ - if_indextoname.3 inet_net.3 link_addr.3 ns.3 ipx.3 \ - rcmd.3 rcmdsh.3 resolver.3 net_addrcmp.3 \ - inet6_option_space.3 inet6_rthdr_space.3 \ - getrrsetbyname.3 +MAN+= byteorder.3 ethers.3 gai_strerror.3 getaddrinfo.3 gethostbyname.3 \ + getifaddrs.3 getnameinfo.3 getnetent.3 getprotoent.3 \ + getrrsetbyname.3 getservent.3 if_indextoname.3 inet.3 \ + inet_net.3 inet6_option_space.3 inet6_rthdr_space.3 \ + ipx.3 link_addr.3 net_addrcmp.3 ns.3 \ + rcmd.3 rcmdsh.3 resolver.3 MLINKS+=byteorder.3 htonl.3 byteorder.3 htons.3 byteorder.3 ntohl.3 \ byteorder.3 ntohs.3 byteorder.3 htobe16.3 byteorder.3 htobe32.3 \ @@ -44,7 +44,7 @@ MLINKS+=byteorder.3 htonl.3 byteorder.3 htons.3 byteorder.3 ntohl.3 \ byteorder.3 swap64.3 MLINKS+=ethers.3 ether_aton.3 ethers.3 ether_hostton.3 ethers.3 ether_line.3 \ ethers.3 ether_ntoa.3 ethers.3 ether_ntohost.3 ethers.3 ether_addr.3 -MLINKS+= getaddrinfo.3 freeaddrinfo.3 getaddrinfo.3 gai_strerror.3 +MLINKS+=getaddrinfo.3 freeaddrinfo.3 MLINKS+=gethostbyname.3 endhostent.3 gethostbyname.3 gethostbyaddr.3 \ gethostbyname.3 sethostent.3 gethostbyname.3 gethostent.3 \ gethostbyname.3 herror.3 gethostbyname.3 gethostbyname2.3 \ diff --git a/lib/libc/net/gai_strerror.3 b/lib/libc/net/gai_strerror.3 new file mode 100644 index 00000000000..75eb1517f40 --- /dev/null +++ b/lib/libc/net/gai_strerror.3 @@ -0,0 +1,118 @@ +.\" $OpenBSD: gai_strerror.3,v 1.1 2004/12/06 10:46:35 jmc Exp $ +.\" +.\" Copyright (c) 1983, 1987, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" +.\" 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. +.\" +.Dd December 3, 2004 +.Dt GAI_STRERROR 3 +.Os +.\" +.Sh NAME +.Nm gai_strerror +.Nd return EAI_xxx error message +.\" +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/socket.h> +.Fd #include <netdb.h> +.Ft "char *" +.Fn gai_strerror "int ecode" +.\" +.Sh DESCRIPTION +To aid applications in printing error messages based on the +.Dv EAI_xxx +codes returned by +.Xr getaddrinfo 3 +and +.Xr getnameinfo 3 , +.Fn gai_strerror +is defined. +The argument is one of the +.Dv EAI_xxx +values detailed below +and the return value points to a string describing the error. +If the argument is not one of the +.Dv EAI_xxx +values, +the function still returns a pointer to a string whose contents +indicate an unknown error. +.Pp +The error return status from +.Xr getaddrinfo 3 +and +.Xr getnameinfo 3 +is zero on success and non-zero on errors. +Non-zero error codes are defined in +.Aq Pa netdb.h , +and are as follows: +.Pp +.Bl -tag -width "EAI_ADDRFAMILYXX" -offset indent -compact +.It Dv EAI_ADDRFAMILY +Address family for +.Fa nodename +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 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 nodename . +.It Dv EAI_NONAME +.Fa nodename +nor +.Fa servname +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 SEE ALSO +.Xr getaddrinfo 3 , +.Xr getnameinfo 3 +.Sh HISTORY +The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. diff --git a/lib/libc/net/getaddrinfo.3 b/lib/libc/net/getaddrinfo.3 index ed8b082970b..e74fdf6ed7a 100644 --- a/lib/libc/net/getaddrinfo.3 +++ b/lib/libc/net/getaddrinfo.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getaddrinfo.3,v 1.28 2004/04/14 10:06:03 jmc Exp $ +.\" $OpenBSD: getaddrinfo.3,v 1.29 2004/12/06 10:46:35 jmc Exp $ .\" $KAME: getaddrinfo.3,v 1.29 2001/02/12 09:24:45 itojun Exp $ .\" .\" Copyright (c) 1983, 1987, 1991, 1993 @@ -36,8 +36,7 @@ .\" .Sh NAME .Nm getaddrinfo , -.Nm freeaddrinfo , -.Nm gai_strerror +.Nm freeaddrinfo .Nd nodename-to-address translation in protocol-independent manner .\" .Sh SYNOPSIS @@ -49,8 +48,6 @@ "const struct addrinfo *hints" "struct addrinfo **res" .Ft void .Fn freeaddrinfo "struct addrinfo *ai" -.Ft "char *" -.Fn gai_strerror "int ecode" .\" .Sh DESCRIPTION The @@ -62,6 +59,67 @@ and .Xr getservbyname 3 , but in a more sophisticated manner. .Pp +All of the information returned by +.Fn getaddrinfo +is dynamically allocated: +the +.Li addrinfo +structures, the socket address structures, and canonical node name +strings pointed to by the addrinfo structures. +To return this information to the system the function +.Fn freeaddrinfo +is called. +The +.Fa addrinfo +structure pointed to by the +.Fa ai +argument is freed, +along with any dynamic storage pointed to by the structure. +This operation is repeated until a +.Dv NULL +.Fa ai_next +pointer is encountered. +.Pp +To aid applications in printing error messages based on the +.Dv EAI_xxx +codes returned by +.Fn getaddrinfo , +.Fn gai_strerror +is defined. +See +.Xr gai_strerror 3 +for more information. +.Pp +The implementation allows experimental numeric IPv6 address notation with +scope identifier. +By appending the percent character and scope identifier to addresses, +you can fill the +.Li sin6_scope_id +field for addresses. +This would make management of scoped address easier, +and allows cut-and-paste input of scoped address. +.Pp +At this moment the code supports only link-local addresses with the format. +Scope identifier is hardcoded to the name of the hardware interface associated +with the link +.Po +such as +.Li ne0 +.Pc . +An example is +.Dq Li fe80::1%ne0 , +which means +.Do +.Li fe80::1 +on the link associated with the +.Li ne0 +interface +.Dc . +.Pp +The IPv6 implementation is still very experimental and non-standard. +The current implementation assumes a one-to-one relationship between +the interface and link, which is not necessarily true from the specification. +.Pp The .Li addrinfo structure is defined as a result of including the @@ -168,7 +226,7 @@ structure the three members and .Fa ai_protocol are the corresponding arguments for a call to the -.Fn socket +.Xr socket 2 function. In each .Li addrinfo @@ -179,15 +237,17 @@ specified by the .Fa ai_addrlen member. .Pp +The +.Fa ai_flags +argument can be set to any of the following values, OR'd together: +.Bl -tag -width "AI_NUMERICHOSTXX" +.It AI_PASSIVE If the .Dv AI_PASSIVE -bit is set in the -.Fa ai_flags -member of the -.Fa hints -structure, then the caller plans to use the returned socket address +bit is set, +the caller plans to use the returned socket address structure in a call to -.Fn bind . +.Xr bind 2 . In this case, if the .Fa nodename argument is a null pointer, then the IP address portion of the socket @@ -199,73 +259,64 @@ for an IPv6 address. .Pp If the .Dv AI_PASSIVE -bit is not set in the -.Fa ai_flags -member of the -.Fa hints -structure, then the returned socket address structure will be ready for a +bit is not set, +the returned socket address structure will be ready for a call to -.Fn connect +.Xr connect 2 .Pq for a connection-oriented protocol or either -.Fn connect , -.Fn sendto , +.Xr connect 2 , +.Xr sendto 2 , or -.Fn sendmsg +.Xr sendmsg 2 .Pq for a connectionless protocol . In this case, if the .Fa nodename argument is a null pointer, then the IP address portion of the socket address structure will be set to the loopback address. -.Pp +.It AI_CANONNAME If the .Dv AI_CANONNAME -bit is set in the -.Fa ai_flags -member of the -.Fa hints -structure, then upon successful return the +bit is set, +then upon successful return the .Fa ai_canonname member of the first .Li addrinfo structure in the linked list will point to a NUL-terminated string containing the canonical name of the specified .Fa nodename . -.Pp +.It AI_NUMERICHOST If the .Dv AI_NUMERICHOST -bit is set in the -.Fa ai_flags -member of the -.Fa hints -structure, then a non-null +bit is set, +then a non-null .Fa nodename string must be a numeric host address string. Otherwise an error of .Dv EAI_NONAME is returned. -This flag prevents any type of name resolution service (e.g., the DNS) +This flag prevents any type of name resolution service, +such as DNS, from being called. -.Pp +.It AI_NUMERICSERV If the .Dv AI_NUMERICSERV -bit is set in the -.Fa ai_flags -member of the -.Fa hints -structure, then a non-null +bit is set, +then a non-null .Fa servname string must be a numeric port string. Otherwise an error of .Dv EAI_NONAME is returned. -This flag prevents any type of name resolution service (e.g., the NIS) +This flag prevents any type of name resolution service, +such as NIS, from being called. +.El .Pp The arguments to .Fn getaddrinfo -must sufficiently be consistent and unambiguous. -Here are pitfall cases you may encounter: +must be sufficiently consistent and unambiguous. +Issues to watch out for are: .Bl -bullet .It .Fn getaddrinfo @@ -322,72 +373,13 @@ does not identify any socket type, and .Fn getaddrinfo is not allowed to glob the argument in such case. .El -.Pp -All of the information returned by -.Fn getaddrinfo -is dynamically allocated: -the -.Li addrinfo -structures, the socket address structures, and canonical node name -strings pointed to by the addrinfo structures. -To return this information to the system the function -.Fn freeaddrinfo -is called. -The -.Fa addrinfo -structure pointed to by the -.Fa ai argument -is freed, along with any dynamic storage pointed to by the structure. -This operation is repeated until a -.Dv NULL -.Fa ai_next -pointer is encountered. -.Pp -To aid applications in printing error messages based on the -.Dv EAI_xxx -codes returned by -.Fn getaddrinfo , -.Fn gai_strerror -is defined. -The argument is one of the -.Dv EAI_xxx -values defined earlier and the return value points to a string describing -the error. -If the argument is not one of the -.Dv EAI_xxx -values, the function still returns a pointer to a string whose contents -indicate an unknown error. .\" -.Ss Extension for scoped IPv6 address -The implementation allows experimental numeric IPv6 address notation with -scope identifier. -By appending the percent character and scope identifier to addresses, -you can fill the -.Li sin6_scope_id -field for addresses. -This would make management of scoped address easier, -and allows cut-and-paste input of scoped address. -.Pp -At this moment the code supports only link-local addresses with the format. -Scope identifier is hardcoded to the name of the hardware interface associated -with the link. -.Po -such as -.Li ne0 -.Pc . -An example is -.Dq Li fe80::1%ne0 , -which means -.Do -.Li fe80::1 -on the link associated with the -.Li ne0 -interface -.Dc . -.Pp -The implementation is still very experimental and non-standard. -The current implementation assumes a one-to-one relationship between -the interface and link, which is not necessarily true from the specification. +.Sh RETURN VALUES +.Fn getaddrinfo +returns zero on success, and non-zero on errors. +See +.Xr gai_strerror 3 +for a description of the non-zero error codes. .\" .Sh EXAMPLES The following code tries to connect to @@ -489,60 +481,8 @@ if (nsock == 0) { freeaddrinfo(res0); .Ed .\" -.Sh DIAGNOSTICS -Error return status from -.Fn getaddrinfo -is zero on success and non-zero on errors. -Non-zero error codes are defined in -.Aq Pa netdb.h , -and as follows: -.Pp -.Bl -tag -width EAI_ADDRFAMILY -compact -.It Dv EAI_ADDRFAMILY -Address family for -.Fa nodename -not supported. -.It Dv EAI_AGAIN -Temporary failure in name resolution. -.It Dv EAI_BADFLAGS -Invalid value for -.Fa ai_flags . -.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 nodename . -.It Dv EAI_NONAME -.Fa nodename -nor -.Fa servname -provided, or not known. -.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 -.Pp -If called with proper argument, -.Fn gai_strerror -returns a pointer to a string describing the given error code. -If the argument is not one of the -.Dv EAI_xxx -values, the function still returns a pointer to a string whose contents -indicate an unknown error. -.\" .Sh SEE ALSO +.Xr gai_strerror 3 , .Xr gethostbyname 3 , .Xr getnameinfo 3 , .Xr getservbyname 3 , @@ -589,5 +529,3 @@ The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. .\" .Sh BUGS The current implementation is not thread-safe. -.Pp -The text was shamelessly copied from RFC 2553. diff --git a/lib/libc/net/getnameinfo.3 b/lib/libc/net/getnameinfo.3 index 3b3a0fd2906..c01646c8a73 100644 --- a/lib/libc/net/getnameinfo.3 +++ b/lib/libc/net/getnameinfo.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getnameinfo.3,v 1.27 2003/08/28 10:16:38 jmc Exp $ +.\" $OpenBSD: getnameinfo.3,v 1.28 2004/12/06 10:46:35 jmc Exp $ .\" $KAME: getnameinfo.3,v 1.20 2001/01/05 13:37:37 itojun Exp $ .\" .\" Copyright (c) 1983, 1987, 1991, 1993 @@ -64,6 +64,24 @@ 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. .Pp +To aid applications in printing error messages based on the +.Dv EAI_xxx +codes returned by +.Fn getnameinfo , +.Fn gai_strerror +is defined. +See +.Xr gai_strerror 3 +for more information. +.Pp +The implementation allows experimental numeric IPv6 address notation with +scope identifier. +IPv6 link-local address will appear as a string like +.Dq Li fe80::1%ne0 . +Refer to +.Xr getaddrinfo 3 +for the notation. +.Pp The first argument, .Fa sa , points to either a @@ -106,7 +124,7 @@ 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 +.Bd -literal -offset indent #define NI_MAXHOST MAXHOSTNAMELEN #define NI_MAXSERV 32 .Ed @@ -122,30 +140,41 @@ Assigned Numbers RFC. The final argument is a .Fa flag that changes the default actions of this function. +The flags are defined in +.Aq Pa netdb.h +and are as follows: +.Bl -tag -width "NI_NUMERICHOSTXX" +.It Dv NI_NOFQDN By default the fully-qualified domain name (FQDN) for the host is -looked up in the DNS and returned. +looked up using 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 +.It Dv NI_NUMERICHOST If the .Fa flag bit .Dv NI_NUMERICHOST -is set, or if the host's name cannot be located in the DNS, +is set, or if the host's name cannot be located using DNS, the numeric form of the host's address is returned instead of its name .Po e.g., by calling -.Fn inet_ntop +.Xr inet_ntop 3 instead of -.Fn gethostbyaddr +.Xr gethostbyaddr 3 .Pc . +The two +.Dv NI_NUMERICxxx +flags are required to support the +.Fl n +flag that many commands provide. +.It Dv NI_NAMEREQD 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 +is set, an error is returned if the host's name cannot be located using DNS. +.It Dv NI_NUMERICSERV If the flag bit .Dv NI_NUMERICSERV is set, the numeric form of the service address is returned @@ -156,35 +185,29 @@ The two flags are required to support the .Fl n flag that many commands provide. -.Pp +.It Dv NI_DGRAM A fifth flag bit, .Dv NI_DGRAM , specifies that the service is a datagram service, and causes -.Fn getservbyport +.Xr getservbyport 3 to be called with a second argument of .Qq udp instead of its default of .Qq tcp . This is required for the few ports (512-514) that have different services for UDP and TCP. -.Pp -These -.Dv NI_xxx -flags are defined in -.Aq Pa netdb.h . +.El .\" -.Ss Extension for scoped IPv6 address -The implementation allows experimental numeric IPv6 address notation with -scope identifier. -IPv6 link-local address will appear as a string like -.Dq Li fe80::1%ne0 . -Refer to -.Xr getaddrinfo 3 -for the notation. +.Sh RETURN VALUES +.Fn getnameinfo +returns zero on success, and non-zero on errors. +See +.Xr gai_strerror 3 +for a description of the non-zero error codes. .\" .Sh EXAMPLES The following code tries to get a numeric hostname, and service name, -for given socket address. +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 */ @@ -198,7 +221,7 @@ if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(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 reverse address mapping: .Bd -literal -offset indent struct sockaddr *sa; /* input */ char hbuf[NI_MAXHOST]; @@ -211,34 +234,8 @@ if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, 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 , @@ -340,8 +337,6 @@ if (error == 0) { .Sh BUGS The current implementation is not thread-safe. .Pp -The text was shamelessly copied from RFC 2553. -.Pp .Ox intentionally uses a different .Dv NI_MAXHOST |