diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/libc/net/Makefile.inc | 8 | ||||
| -rw-r--r-- | lib/libc/net/gai_strerror.3 | 118 | ||||
| -rw-r--r-- | lib/libc/net/getaddrinfo.3 | 531 | ||||
| -rw-r--r-- | lib/libc/net/getnameinfo.3 | 343 | ||||
| -rw-r--r-- | lib/libc/net/inet6_option_space.3 | 444 | ||||
| -rw-r--r-- | lib/libc/net/inet6_rthdr_space.3 | 317 |
6 files changed, 4 insertions, 1757 deletions
diff --git a/lib/libc/net/Makefile.inc b/lib/libc/net/Makefile.inc index 79bfbb6b915..3d959d6be09 100644 --- a/lib/libc/net/Makefile.inc +++ b/lib/libc/net/Makefile.inc @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile.inc,v 1.35 2004/12/06 10:46:35 jmc Exp $ +# $OpenBSD: Makefile.inc,v 1.36 2004/12/20 03:26:43 itojun Exp $ # net sources .PATH: ${LIBCSRCDIR}/arch/${MACHINE_ARCH}/net ${LIBCSRCDIR}/net @@ -28,10 +28,10 @@ SRCS+= ip6opt.c rthdr.c vars6.c .include "${LIBCSRCDIR}/arch/${MACHINE_ARCH}/net/Makefile.inc" -MAN+= byteorder.3 ethers.3 gai_strerror.3 getaddrinfo.3 gethostbyname.3 \ - getifaddrs.3 getnameinfo.3 getnetent.3 getprotoent.3 \ +MAN+= byteorder.3 ethers.3 gethostbyname.3 \ + getifaddrs.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 \ + inet_net.3 \ ipx.3 link_addr.3 net_addrcmp.3 ns.3 \ rcmd.3 rcmdsh.3 resolver.3 diff --git a/lib/libc/net/gai_strerror.3 b/lib/libc/net/gai_strerror.3 deleted file mode 100644 index 75eb1517f40..00000000000 --- a/lib/libc/net/gai_strerror.3 +++ /dev/null @@ -1,118 +0,0 @@ -.\" $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 deleted file mode 100644 index e74fdf6ed7a..00000000000 --- a/lib/libc/net/getaddrinfo.3 +++ /dev/null @@ -1,531 +0,0 @@ -.\" $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 -.\" 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. -.\" -.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 -.\" -.Dd May 25, 1995 -.Dt GETADDRINFO 3 -.Os -.\" -.Sh NAME -.Nm getaddrinfo , -.Nm freeaddrinfo -.Nd nodename-to-address translation in protocol-independent manner -.\" -.Sh SYNOPSIS -.Fd #include <sys/types.h> -.Fd #include <sys/socket.h> -.Fd #include <netdb.h> -.Ft int -.Fn getaddrinfo "const char *nodename" "const char *servname" \ -"const struct addrinfo *hints" "struct addrinfo **res" -.Ft void -.Fn freeaddrinfo "struct addrinfo *ai" -.\" -.Sh DESCRIPTION -The -.Fn getaddrinfo -function is defined for protocol-independent nodename-to-address translation. -It performs the functionality of -.Xr gethostbyname 3 -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 -.Aq Pa netdb.h -header: -.Bd -literal -struct addrinfo { - int ai_flags; /* input flags */ - int ai_family; /* protocol family for socket */ - int ai_socktype; /* socket type */ - int ai_protocol; /* protocol for socket */ - socklen_t ai_addrlen; /* length of socket-address */ - struct sockaddr *ai_addr; /* socket-address for socket */ - char *ai_canonname; /* canonical name for service location */ - struct addrinfo *ai_next; /* pointer to next in list */ -}; -.Ed -.Pp -The -.Fa nodename -and -.Fa servname -arguments are pointers to NUL-terminated strings or -.Dv NULL . -One or both of these two arguments must be a non-null pointer. -In the normal client scenario, both the -.Fa nodename -and -.Fa servname -are specified. -In the normal server scenario, only the -.Fa servname -is specified. -A non-null -.Fa nodename -string can be either a node name or a numeric host address string -(i.e., a dotted-decimal IPv4 address or an IPv6 hex address). -A non-null -.Fa servname -string can be either a service name or a decimal port number. -.Pp -The caller can optionally pass an -.Li addrinfo -structure, pointed to by the third argument, -to provide hints concerning the type of socket that the caller supports. -In this -.Fa hints -structure all members other than -.Fa ai_flags , -.Fa ai_family , -.Fa ai_socktype , -and -.Fa ai_protocol -must be zero or a null pointer. -A value of -.Dv PF_UNSPEC -for -.Fa ai_family -means the caller will accept any protocol family. -A value of 0 for -.Fa ai_socktype -means the caller will accept any socket type. -A value of 0 for -.Fa ai_protocol -means the caller will accept any protocol. -For example, if the caller handles only TCP and not UDP, then the -.Fa ai_socktype -member of the hints structure should be set to -.Dv SOCK_STREAM -when -.Fn getaddrinfo -is called. -If the caller handles only IPv4 and not IPv6, then the -.Fa ai_family -member of the -.Fa hints -structure should be set to -.Dv PF_INET -when -.Fn getaddrinfo -is called. -If the third argument to -.Fn getaddrinfo -is a null pointer, this is the same as if the caller had filled in an -.Li addrinfo -structure initialized to zero with -.Fa ai_family -set to -.Dv PF_UNSPEC . -.Pp -Upon successful return a pointer to a linked list of one or more -.Li addrinfo -structures is returned through the final argument. -The caller can process each -.Li addrinfo -structure in this list by following the -.Fa ai_next -pointer, until a null pointer is encountered. -In each returned -.Li addrinfo -structure the three members -.Fa ai_family , -.Fa ai_socktype , -and -.Fa ai_protocol -are the corresponding arguments for a call to the -.Xr socket 2 -function. -In each -.Li addrinfo -structure the -.Fa ai_addr -member points to a filled-in socket address structure whose length is -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, -the caller plans to use the returned socket address -structure in a call to -.Xr bind 2 . -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 -.Dv INADDR_ANY -for an IPv4 address or -.Dv IN6ADDR_ANY_INIT -for an IPv6 address. -.Pp -If the -.Dv AI_PASSIVE -bit is not set, -the returned socket address structure will be ready for a -call to -.Xr connect 2 -.Pq for a connection-oriented protocol -or either -.Xr connect 2 , -.Xr sendto 2 , -or -.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. -.It AI_CANONNAME -If the -.Dv AI_CANONNAME -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 . -.It AI_NUMERICHOST -If the -.Dv AI_NUMERICHOST -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, -such as DNS, -from being called. -.It AI_NUMERICSERV -If the -.Dv AI_NUMERICSERV -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, -such as NIS, -from being called. -.El -.Pp -The arguments to -.Fn getaddrinfo -must be sufficiently consistent and unambiguous. -Issues to watch out for are: -.Bl -bullet -.It -.Fn getaddrinfo -will raise an error if members of the -.Fa hints -structure are not consistent. -For example, for internet address families, -.Fn getaddrinfo -will raise an error if you specify -.Dv SOCK_STREAM -to -.Fa ai_socktype -while you specify -.Dv IPPROTO_UDP -to -.Fa ai_protocol . -.It -If you specify a -.Fa servname -which is defined only for certain -.Fa ai_socktype , -.Fn getaddrinfo -will raise an error because the arguments are not consistent. -For example, -.Fn getaddrinfo -will raise an error if you ask for -.Dq Li tftp -service on -.Dv SOCK_STREAM . -.It -For internet address families, if you specify -.Fa servname -while you set -.Fa ai_socktype -to -.Dv SOCK_RAW , -.Fn getaddrinfo -will raise an error, because service names are not defined for the internet -.Dv SOCK_RAW -space. -.It -If you specify a numeric -.Fa servname , -while leaving -.Fa ai_socktype -and -.Fa ai_protocol -unspecified, -.Fn getaddrinfo -will raise an error. -This is because the numeric -.Fa servname -does not identify any socket type, and -.Fn getaddrinfo -is not allowed to glob the argument in such case. -.El -.\" -.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 -.Dq Li www.kame.net -service -.Dq Li http . -via stream socket. -It loops through all the addresses available, regardless of address family. -If the destination resolves to an IPv4 address, it will use -.Dv AF_INET -socket. -Similarly, if it resolves to IPv6, -.Dv AF_INET6 -socket is used. -Observe that there is no hardcoded reference to a particular address family. -The code works even if -.Nm getaddrinfo -returns addresses that are not IPv4/v6. -.Bd -literal -offset indent -struct addrinfo hints, *res, *res0; -int error; -int s; -const char *cause = NULL; - -memset(&hints, 0, sizeof(hints)); -hints.ai_family = PF_UNSPEC; -hints.ai_socktype = SOCK_STREAM; -error = getaddrinfo("www.kame.net", "http", &hints, &res0); -if (error) { - errx(1, "%s", gai_strerror(error)); - /*NOTREACHED*/ -} -s = -1; -for (res = res0; res; res = res->ai_next) { - s = socket(res->ai_family, res->ai_socktype, - res->ai_protocol); - if (s < 0) { - cause = "socket"; - continue; - } - - if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { - cause = "connect"; - close(s); - s = -1; - continue; - } - - break; /* okay we got one */ -} -if (s < 0) { - err(1, "%s", cause); - /*NOTREACHED*/ -} -freeaddrinfo(res0); -.Ed -.Pp -The following example tries to open a wildcard listening socket onto service -.Dq Li http , -for all the address families available. -.Bd -literal -offset indent -struct addrinfo hints, *res, *res0; -int error; -int s[MAXSOCK]; -int nsock; -const char *cause = NULL; - -memset(&hints, 0, sizeof(hints)); -hints.ai_family = PF_UNSPEC; -hints.ai_socktype = SOCK_STREAM; -hints.ai_flags = AI_PASSIVE; -error = getaddrinfo(NULL, "http", &hints, &res0); -if (error) { - errx(1, "%s", gai_strerror(error)); - /*NOTREACHED*/ -} -nsock = 0; -for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { - s[nsock] = socket(res->ai_family, res->ai_socktype, - res->ai_protocol); - if (s[nsock] < 0) { - cause = "socket"; - continue; - } - - if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { - cause = "bind"; - close(s[nsock]); - continue; - } - (void) listen(s[nsock], 5); - - nsock++; -} -if (nsock == 0) { - err(1, "%s", cause); - /*NOTREACHED*/ -} -freeaddrinfo(res0); -.Ed -.\" -.Sh SEE ALSO -.Xr gai_strerror 3 , -.Xr gethostbyname 3 , -.Xr getnameinfo 3 , -.Xr getservbyname 3 , -.Xr hosts 5 , -.Xr resolv.conf 5 , -.Xr services 5 , -.Xr hostname 7 , -.Xr named 8 -.Rs -.%A R. Gilligan -.%A S. Thomson -.%A J. Bound -.%A J. McCann -.%A W. Stevens -.%T Basic Socket Interface Extensions for IPv6 -.%R RFC 3493 -.%D February 2003 -.Re -.Rs -.%A Tatsuya Jinmei -.%A Atsushi Onoe -.%T "An Extension of Format for IPv6 Scoped Addresses" -.%R internet draft -.%N draft-ietf-ipngwg-scopedaddr-format-02.txt -.%O work in progress material -.Re -.Rs -.%A Craig Metz -.%T Protocol Independence Using the Sockets API -.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" -.%D June 2000 -.Re -.\" -.Sh STANDARDS -The -.Fn getaddrinfo -function is defined in IEEE POSIX 1003.1g draft specification, -and documented in -.Dq Basic Socket Interface Extensions for IPv6 -.Pq RFC 3493 . -.\" -.Sh HISTORY -The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. -.\" -.Sh BUGS -The current implementation is not thread-safe. diff --git a/lib/libc/net/getnameinfo.3 b/lib/libc/net/getnameinfo.3 deleted file mode 100644 index c01646c8a73..00000000000 --- a/lib/libc/net/getnameinfo.3 +++ /dev/null @@ -1,343 +0,0 @@ -.\" $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 -.\" 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. -.\" -.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 -.\" -.Dd May 25, 1995 -.Dt GETNAMEINFO 3 -.Os -.\" -.Sh NAME -.Nm getnameinfo -.Nd address-to-nodename translation in protocol-independent manner -.\" -.Sh SYNOPSIS -.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" "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 -.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. -.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 -.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_in -or -.Li sockaddr_in6 -structure. -.Pp -The function returns the nodename associated with the IP address in -the buffer pointed to by the -.Fa host -argument. -The caller provides the size of this buffer via the -.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 -.Fa hostlen -or -.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 indent -#define NI_MAXHOST MAXHOSTNAMELEN -#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 (older versions of BIND define this constant to be 256) -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. -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 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. -.It Dv NI_NUMERICHOST -If the -.Fa flag -bit -.Dv NI_NUMERICHOST -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 -.Xr inet_ntop 3 -instead of -.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 using DNS. -.It Dv NI_NUMERICSERV -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. -.It Dv NI_DGRAM -A fifth flag bit, -.Dv NI_DGRAM , -specifies that the service is a datagram service, and causes -.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. -.El -.\" -.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 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->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\en", hbuf, sbuf); -.Ed -.Pp -The following version checks if the socket address has reverse address mapping: -.Bd -literal -offset indent -struct sockaddr *sa; /* input */ -char hbuf[NI_MAXHOST]; - -if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, - NI_NAMEREQD)) { - errx(1, "could not resolve hostname"); - /*NOTREACHED*/ -} -printf("host=%s\en", hbuf); -.Ed -.\" -.Sh SEE ALSO -.Xr gai_strerror 3 , -.Xr getaddrinfo 3 , -.Xr gethostbyaddr 3 , -.Xr getservbyport 3 , -.Xr hosts 5 , -.Xr resolv.conf 5 , -.Xr services 5 , -.Xr hostname 7 , -.Xr named 8 -.Rs -.%A R. Gilligan -.%A S. Thomson -.%A J. Bound -.%A W. Stevens -.%T Basic Socket Interface Extensions for IPv6 -.%R RFC 2553 -.%D March 1999 -.Re -.Rs -.%A Tatsuya Jinmei -.%A Atsushi Onoe -.%T "An Extension of Format for IPv6 Scoped Addresses" -.%R internet draft -.%N draft-ietf-ipngwg-scopedaddr-format-02.txt -.%O work in progress material -.Re -.Rs -.%A Craig Metz -.%T Protocol Independence Using the Sockets API -.%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. -.\" -.Sh CAVEATS -.Fn getnameinfo -returns both numeric and FQDN notation of the address specified in -.Fa sa . -There is no return value that indicates if 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 as below: -.Bd -literal -offset indent -1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 -.Ed -.Pp -and trick the caller of -.Fn getnameinfo -into believing that -.Fa sa -is -.Li 10.1.1.1 -when it actually is -.Li 127.0.0.1 . -.Pp -To prevent such attacks, the use of -.Dv NI_NAMEREQD -is recommended when you use the result of -.Fn getnameinfo -for access control purposes: -.Bd -literal -offset indent -struct sockaddr *sa; -socklen_t salen; -char addr[NI_MAXHOST]; -struct addrinfo hints, *res; -int error; - -error = getnameinfo(sa, salen, addr, sizeof(addr), - NULL, 0, NI_NAMEREQD); -if (error == 0) { - memset(&hints, 0, sizeof(hints)); - hints.ai_socktype = SOCK_DGRAM; /*dummy*/ - hints.ai_flags = AI_NUMERICHOST; - if (getaddrinfo(addr, "0", &hints, &res) == 0) { - /* malicious PTR record */ - freeaddrinfo(res); - printf("bogus PTR record\\n"); - return -1; - } - /* addr is FQDN as a result of PTR lookup */ -} else { - /* addr is numeric string */ - error = getnameinfo(sa, salen, addr, sizeof(addr), - NULL, 0, NI_NUMERICHOST); -} -.Ed -.\" -.Sh BUGS -The current implementation is not thread-safe. -.Pp -.Ox -intentionally uses a different -.Dv NI_MAXHOST -value from what RFC 2553 suggests, to avoid buffer length handling mistakes. diff --git a/lib/libc/net/inet6_option_space.3 b/lib/libc/net/inet6_option_space.3 deleted file mode 100644 index 4e5dc22711a..00000000000 --- a/lib/libc/net/inet6_option_space.3 +++ /dev/null @@ -1,444 +0,0 @@ -.\" $OpenBSD: inet6_option_space.3,v 1.13 2003/08/08 09:26:02 jmc Exp $ -.\" $KAME: inet6_option_space.3,v 1.7 2000/05/17 14:32:13 itojun 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 10, 1999 -.Dt INET6_OPTION_SPACE 3 -.Os -.\" -.Sh NAME -.Nm inet6_option_space , -.Nm inet6_option_init , -.Nm inet6_option_append , -.Nm inet6_option_alloc , -.Nm inet6_option_next , -.Nm inet6_option_find -.Nd IPv6 Hop-by-Hop and Destination Options manipulation -.\" -.Sh SYNOPSIS -.Fd #include <netinet/in.h> -.Ft "int" -.Fn inet6_option_space "int nbytes" -.Ft "int" -.Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type" -.Ft "int" -.Fn inet6_option_append "struct cmsghdr *cmsg" "const u_int8_t *typep" "int multx" "int plusy" -.Ft "u_int8_t *" -.Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy" -.Ft "int" -.Fn inet6_option_next "const struct cmsghdr *cmsg" "u_int8_t **tptrp" -.Ft "int" -.Fn inet6_option_find "const struct cmsghdr *cmsg" "u_int8_t **tptrp" "int type" -.\" -.Sh DESCRIPTION -.\" -Building and parsing the Hop-by-Hop and Destination options is -complicated due to alignment constraints, padding and -ancillary data manipulation. -RFC 2292 defines a set of functions to help the application. -The function prototypes for -these functions are all in the -.Aq Pa netinet/in.h -header. -.\" -.Ss inet6_option_space -.Fn inet6_option_space -returns the number of bytes required to hold an option when it is stored as -ancillary data, including the -.Li cmsghdr -structure at the beginning, -and any padding at the end -.Po -to make its size a multiple of 8 bytes -.Pc . -The argument is the size of the structure defining the option, -which must include any pad bytes at the beginning -.Po -the value -.Li y -in the alignment term -.Dq Li xn + y -.Pc , -the type byte, the length byte, and the option data. -.Pp -Note: If multiple options are stored in a single ancillary data -object, which is the recommended technique, this function -overestimates the amount of space required by the size of -.Li N-1 -.Li cmsghdr -structures, -where -.Li N -is the number of options to be stored in the object. -This is of little consequence, since it is assumed that most -Hop-by-Hop option headers and Destination option headers carry only -one option -.Pq appendix B of [RFC 2460] . -.\" -.Ss inet6_option_init -.Fn inet6_option_init -is called once per ancillary data object that will -contain either Hop-by-Hop or Destination options. -It returns -.Li 0 -on success or -.Li -1 -on an error. -.Pp -.Fa bp -is a pointer to previously allocated space that will contain the -ancillary data object. -It must be large enough to contain all the -individual options to be added by later calls to -.Fn inet6_option_append -and -.Fn inet6_option_alloc . -.Pp -.Fa cmsgp -is a pointer to a pointer to a -.Li cmsghdr -structure. -.Fa *cmsgp -is initialized by this function to point to the -.Li cmsghdr -structure constructed by this function in the buffer pointed to by -.Fa bp . -.Pp -.Fa type -is either -.Dv IPV6_HOPOPTS -or -.Dv IPV6_DSTOPTS . -This -.Fa type -is stored in the -.Li cmsg_type -member of the -.Li cmsghdr -structure pointed to by -.Fa *cmsgp . -.\" -.Ss inet6_option_append -This function appends a Hop-by-Hop option or a Destination option -into an ancillary data object that has been initialized by -.Fn inet6_option_init . -This function returns -.Li 0 -if it succeeds or -.Li -1 -on an error. -.Pp -.Fa cmsg -is a pointer to the -.Li cmsghdr -structure that must have been -initialized by -.Fn inet6_option_init . -.Pp -.Fa typep -is a pointer to the 8-bit option type. -It is assumed that this -field is immediately followed by the 8-bit option data length field, -which is then followed immediately by the option data. -The caller -initializes these three fields -.Pq the type-length-value, or TLV -before calling this function. -.Pp -The option type must have a value from -.Li 2 -to -.Li 255 , -inclusive. -.Po -.Li 0 -and -.Li 1 -are reserved for the -.Li Pad1 -and -.Li PadN -options, respectively. -.Pc -.Pp -The option data length must have a value between -.Li 0 -and -.Li 255 , -inclusive, and is the length of the option data that follows. -.Pp -.Fa multx -is the value -.Li x -in the alignment term -.Dq Li xn + y . -It must have a value of -.Li 1 , -.Li 2 , -.Li 4 , -or -.Li 8 . -.Pp -.Fa plusy -is the value -.Li y -in the alignment term -.Dq Li xn + y . -It must have a value between -.Li 0 -and -.Li 7 , -inclusive. -.\" -.Ss inet6_option_alloc -This function appends a Hop-by-Hop option or a Destination option -into an ancillary data object that has been initialized by -.Fn inet6_option_init . -This function returns a pointer to the 8-bit -option type field that starts the option on success, or -.Dv NULL -on an error. -.Pp -The difference between this function and -.Fn inet6_option_append -is that the latter copies the contents of a previously built option into -the ancillary data object while the current function returns a -pointer to the space in the data object where the option's TLV must -then be built by the caller. -.Pp -.Fa cmsg -is a pointer to the -.Li cmsghdr -structure that must have been -initialized by -.Fn inet6_option_init . -.Pp -.Fa datalen -is the value of the option data length byte for this option. -This value is required as an argument to allow the function to -determine if padding must be appended at the end of the option. -(The -.Fn inet6_option_append -function does not need a data length argument -since the option data length must already be stored by the caller.) -.Pp -.Fa multx -is the value -.Li x -in the alignment term -.Dq Li xn + y . -It must have a value of -.Li 1 , -.Li 2 , -.Li 4 , -or -.Li 8 . -.Pp -.Fa plusy -is the value -.Li y -in the alignment term -.Dq Li xn + y . -It must have a value between -.Li 0 -and -.Li 7 , -inclusive. -.\" -.Ss inet6_option_next -This function processes the next Hop-by-Hop option or Destination -option in an ancillary data object. -If another option remains to be -processed, the return value of the function is -.Li 0 -and -.Fa *tptrp -points to -the 8-bit option type field -(which is followed by the 8-bit option -data length, followed by the option data). -If no more options remain -to be processed, the return value is -.Li -1 -and -.Fa *tptrp -is -.Dv NULL . -If an error occurs, the return value is -.Li -1 -and -.Fa *tptrp -is not -.Dv NULL . -.Pp -.Fa cmsg -is a pointer to -.Li cmsghdr -structure of which -.Li cmsg_level -equals -.Dv IPPROTO_IPV6 -and -.Li cmsg_type -equals either -.Dv IPV6_HOPOPTS -or -.Dv IPV6_DSTOPTS . -.Pp -.Fa tptrp -is a pointer to a pointer to an 8-bit byte and -.Fa *tptrp -is used -by the function to remember its place in the ancillary data object -each time the function is called. -The first time this function is -called for a given ancillary data object, -.Fa *tptrp -must be set to -.Dv NULL . -.Pp -Each time this function returns success, -.Fa *tptrp -points to the 8-bit -option type field for the next option to be processed. -.\" -.Ss inet6_option_find -This function is similar to the previously described -.Fn inet6_option_next -function, except this function lets the caller -specify the option type to be searched for, instead of always -returning the next option in the ancillary data object. -.Fa cmsg -is a -pointer to -.Li cmsghdr -structure of which -.Li cmsg_level -equals -.Dv IPPROTO_IPV6 -and -.Li cmsg_type -equals either -.Dv IPV6_HOPOPTS -or -.Dv IPV6_DSTOPTS . -.Pp -.Fa tptrp -is a pointer to a pointer to an 8-bit byte and -.Fa *tptrp -is used -by the function to remember its place in the ancillary data object -each time the function is called. -The first time this function is -called for a given ancillary data object, -.Fa *tptrp -must be set to -.Dv NULL . -.Pp -This function starts searching for an option of the specified type -beginning after the value of -.Fa *tptrp . -If an option of the specified -type is located, this function returns -.Li 0 -and -.Fa *tptrp -points to the 8- -bit option type field for the option of the specified type. -If an -option of the specified type is not located, the return value is -.Li -1 -and -.Fa *tptrp -is -.Dv NULL . -If an error occurs, the return value is -.Li -1 -and -.Fa *tptrp -is not -.Dv NULL . -.\" -.Sh EXAMPLES -RFC 2292 gives comprehensive examples in chapter 6. -.\" -.Sh DIAGNOSTICS -.Fn inet6_option_init -and -.Fn inet6_option_append -return -.Li 0 -on success or -.Li -1 -on an error. -.Pp -.Fn inet6_option_alloc -returns -.Dv NULL -on an error. -.Pp -On errors, -.Fn inet6_option_next -and -.Fn inet6_option_find -return -.Li -1 -setting -.Fa *tptrp -to non -.Dv NULL -value. -.\" -.Sh SEE ALSO -.Rs -.%A W. Stevens -.%A M. Thomas -.%T "Advanced Sockets API for IPv6" -.%N RFC 2292 -.%D February 1998 -.Re -.Rs -.%A S. Deering -.%A R. Hinden -.%T "Internet Protocol, Version 6 (IPv6) Specification" -.%N RFC 2460 -.%D December 1998 -.Re -.\" -.Sh STANDARDS -The functions -are documented in -.Dq Advanced Sockets API for IPv6 -.Pq RFC 2292 . -.\" -.Sh HISTORY -The implementation first appeared in KAME advanced networking kit. -.\" -.Sh BUGS -The text was shamelessly copied from RFC 2292. diff --git a/lib/libc/net/inet6_rthdr_space.3 b/lib/libc/net/inet6_rthdr_space.3 deleted file mode 100644 index 33b209af4f2..00000000000 --- a/lib/libc/net/inet6_rthdr_space.3 +++ /dev/null @@ -1,317 +0,0 @@ -.\" $OpenBSD: inet6_rthdr_space.3,v 1.13 2003/08/08 09:26:02 jmc Exp $ -.\" $KAME: inet6_rthdr_space.3,v 1.8 2000/05/17 14:30:15 itojun 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 10, 1999 -.Dt INET6_RTHDR_SPACE 3 -.Os -.\" -.Sh NAME -.Nm inet6_rthdr_space , -.Nm inet6_rthdr_init , -.Nm inet6_rthdr_add , -.Nm inet6_rthdr_lasthop , -.Nm inet6_rthdr_reverse , -.Nm inet6_rthdr_segments , -.Nm inet6_rthdr_getaddr , -.Nm inet6_rthdr_getflags -.Nd IPv6 Routing Header Options manipulation -.\" -.Sh SYNOPSIS -.Fd #include <netinet/in.h> -.Ft size_t -.Fn inet6_rthdr_space "int type" "int segments" -.Ft "struct cmsghdr *" -.Fn inet6_rthdr_init "void *bp" "int type" -.Ft int -.Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags" -.Ft int -.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags" -.Ft int -.Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out" -.Ft int -.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg" -.Ft "struct in6_addr *" -.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index" -.Ft int -.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index" -.\" -.Sh DESCRIPTION -RFC 2292 IPv6 advanced API defines eight -functions that the application calls to build and examine a Routing -header. -Four functions build a Routing header: -.Bl -hang -.It Fn inet6_rthdr_space -return #bytes required for ancillary data -.It Fn inet6_rthdr_init -initialize ancillary data for Routing header -.It Fn inet6_rthdr_add -add IPv6 address & flags to Routing header -.It Fn inet6_rthdr_lasthop -specify the flags for the final hop -.El -.Pp -Four functions deal with a returned Routing header: -.Bl -hang -.It Fn inet6_rthdr_reverse -reverse a Routing header -.It Fn inet6_rthdr_segments -return #segments in a Routing header -.It Fn inet6_rthdr_getaddr -fetch one address from a Routing header -.It Fn inet6_rthdr_getflags -fetch one flag from a Routing header -.El -.Pp -The function prototypes for these functions are all in the -.Aq Pa netinet/in.h -header. -.\" -.Ss inet6_rthdr_space -This function returns the number of bytes required to hold a Routing -header of the specified -.Fa type -containing the specified number of -.Fa segments -.Pq addresses . -For an IPv6 Type 0 Routing header, the number -of segments must be between 1 and 23, inclusive. -The return value -includes the size of the cmsghdr structure that precedes the Routing -header, and any required padding. -.Pp -If the return value is 0, then either the type of the Routing header -is not supported by this implementation or the number of segments is -invalid for this type of Routing header. -.Pp -Note: This function returns the size but does not allocate the space -required for the ancillary data. -This allows an application to -allocate a larger buffer, if other ancillary data objects are -desired, since all the ancillary data objects must be specified to -.Xr sendmsg 2 -as a single -.Li msg_control -buffer. -.\" -.Ss inet6_rthdr_init -This function initializes the buffer pointed to by -.Fa bp -to contain a -.Li cmsghdr -structure followed by a Routing header of the specified -.Fa type . -The -.Li cmsg_len -member of the -.Li cmsghdr -structure is initialized to the -size of the structure plus the amount of space required by the -Routing header. -The -.Li cmsg_level -and -.Li cmsg_type -members are also initialized as required. -.Pp -The caller must allocate the buffer and its size can be determined by -calling -.Fn inet6_rthdr_space . -.Pp -Upon success the return value is the pointer to the -.Li cmsghdr -structure, and this is then used as the first argument to the next -two functions. -Upon an error the return value is -.Dv NULL . -.\" -.Ss inet6_rthdr_add -This function adds the address pointed to by -.Fa addr -to the end of the -Routing header being constructed and sets the type of this hop to the -value of -.Fa flags . -For an IPv6 Type 0 Routing header, -.Fa flags -must be -either -.Dv IPV6_RTHDR_LOOSE -or -.Dv IPV6_RTHDR_STRICT . -.Pp -If successful, the -.Li cmsg_len -member of the -.Li cmsghdr -structure is -updated to account for the new address in the Routing header and the -return value of the function is 0. -Upon an error the return value of -the function is -1. -.\" -.Ss inet6_rthdr_lasthop -This function specifies the Strict/Loose flag for the final hop of a -Routing header. -For an IPv6 Type 0 Routing header, -.Fa flags -must be either -.Dv IPV6_RTHDR_LOOSE -or -.Dv IPV6_RTHDR_STRICT . -.Pp -The return value of the function is 0 upon success, or -1 upon an error. -.Pp -Notice that a Routing header specifying -.Li N -intermediate nodes requires -.Li N+1 -Strict/Loose flags. -This requires -.Li N -calls to -.Fn inet6_rthdr_add -followed by one call to -.Fn inet6_rthdr_lasthop . -.\" -.Ss inet6_rthdr_reverse -This function takes a Routing header that was received as ancillary -data -.Po -pointed to by the first argument, -.Fa in -.Pc -and writes a new Routing -header that sends datagrams along the reverse of that route. -Both -arguments are allowed to point to the same buffer -.Pq that is, the reversal can occur in place . -.Pp -The return value of the function is 0 on success, or -1 upon an -error. -.\" -.Ss inet6_rthdr_segments -This function returns the number of segments -.Pq addresses -contained in -the Routing header described by -.Fa cmsg . -On success the return value is -between 1 and 23, inclusive. -The return value of the function is -1 upon an error. -.\" -.Ss inet6_rthdr_getaddr -This function returns a pointer to the IPv6 address specified by -.Fa index -(which must have a value between 1 and the value returned by -.Fn inet6_rthdr_segments ) -in the Routing header described by -.Fa cmsg . -An -application should first call -.Fn inet6_rthdr_segments -to obtain the number of segments in the Routing header. -.Pp -Upon an error the return value of the function is -.Dv NULL . -.\" -.Ss inet6_rthdr_getflags -This function returns the flags value specified by -.Fa index -(which must -have a value between 0 and the value returned by -.Fn inet6_rthdr_segments ) -in the Routing header described by -.Fa cmsg . -For an IPv6 Type 0 Routing header the return value will be either -.Dv IPV6_RTHDR_LOOSE -or -.Dv IPV6_RTHDR_STRICT . -.Pp -Upon an error the return value of the function is -1. -.Pp -Note: Addresses are indexed starting at 1, and flags starting at 0, -to maintain consistency with the terminology and figures in RFC 2460. -.\" -.Sh EXAMPLES -RFC 2292 gives comprehensive examples in chapter 8. -.\" -.Sh DIAGNOSTICS -.Fn inet6_rthdr_space -returns 0 on errors. -.Pp -.Fn inet6_rthdr_add , -.Fn inet6_rthdr_lasthop -and -.Fn inet6_rthdr_reverse -return 0 on success, and returns -1 on error. -.Pp -.Fn inet6_rthdr_init -and -.Fn inet6_rthdr_getaddr -return -.Dv NULL -on error. -.Pp -.Fn inet6_rthdr_segments -and -.Fn inet6_rthdr_getflags -return -1 on error. -.\" -.Sh SEE ALSO -.Rs -.%A W. Stevens -.%A M. Thomas -.%T "Advanced Sockets API for IPv6" -.%N RFC 2292 -.%D February 1998 -.Re -.Rs -.%A S. Deering -.%A R. Hinden -.%T "Internet Protocol, Version 6 (IPv6) Specification" -.%N RFC 2460 -.%D December 1998 -.Re -.\" -.Sh STANDARDS -The functions -are documented in -.Dq Advanced Sockets API for IPv6 -.Pq RFC 2292 . -.\" -.Sh HISTORY -The implementation first appeared in KAME advanced networking kit. -.\" -.Sh BUGS -The text was shamelessly copied from RFC 2292. -.Pp -.Fn inet6_rthdr_reverse -is not implemented yet. |