diff options
| -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 | ||||
| -rw-r--r-- | share/man/man4/Makefile | 6 | ||||
| -rw-r--r-- | share/man/man4/icmp6.4 | 255 | ||||
| -rw-r--r-- | share/man/man4/ip6.4 | 658 |
9 files changed, 7 insertions, 2673 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. diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index a94076d0498..1b960433978 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.283 2004/12/17 00:28:30 jaredy Exp $ +# $OpenBSD: Makefile,v 1.284 2004/12/20 03:26:43 itojun Exp $ MAN= aac.4 ac97.4 acphy.4 addcom.4 adv.4 aha.4 ahb.4 ahc.4 ahd.4 \ aic.4 amdpm.4 ami.4 amphy.4 an.4 aria.4 ast.4 atalk.4 \ @@ -12,9 +12,9 @@ MAN= aac.4 ac97.4 acphy.4 addcom.4 adv.4 aha.4 ahb.4 ahc.4 ahd.4 \ faith.4 fd.4 fdc.4 fms.4 fpa.4 fxp.4 gdt.4 gentbi.4 gem.4 gif.4 \ gpio.4 gpr.4 gre.4 gscsio.4 gtp.4 \ hifn.4 hil.4 hilid.4 hilkbd.4 hilms.4 \ - hme.4 hotplug.4 hsq.4 icmp.4 icmp6.4 icsphy.4 idp.4 ifmedia.4 \ + hme.4 hotplug.4 hsq.4 icmp.4 icsphy.4 idp.4 ifmedia.4 \ iha.4 iic.4 inet.4 inet6.4 inphy.4 iop.4 iophy.4 ioprbs.4 \ - iopsp.4 ip.4 ip6.4 ipcomp.4 ipsec.4 ipw.4 isa.4 isapnp.4 \ + iopsp.4 ip.4 ipcomp.4 ipsec.4 ipw.4 isa.4 isapnp.4 \ ises.4 isp.4 it.4 iwi.4 ksyms.4 kue.4 lc.4 lge.4 lkm.4 \ lm.4 lmc.4 lmtemp.4 lo.4 lofn.4 lpt.4 lxtphy.4 maestro.4 midi.4 \ mii.4 mpt.4 mpu.4 mtd.4 mtdphy.4 mtio.4 ncr.4 ne.4 neo.4 \ diff --git a/share/man/man4/icmp6.4 b/share/man/man4/icmp6.4 deleted file mode 100644 index 81c3447f339..00000000000 --- a/share/man/man4/icmp6.4 +++ /dev/null @@ -1,255 +0,0 @@ -.\" $OpenBSD: icmp6.4,v 1.16 2003/10/22 20:12:25 jmc Exp $ -.\" $KAME: icmp6.4,v 1.3 2000/11/24 08:44:40 itojun Exp $ -.\" -.\" Copyright (C) 1999 WIDE Project. -.\" 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 project 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 PROJECT 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 PROJECT 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. -.\" -.\" Copyright (c) 1986, 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 17, 1999 -.Dt ICMP6 4 -.Os -.Sh NAME -.Nm icmp6 -.Nd Internet Control Message Protocol for IPv6 -.Sh SYNOPSIS -.Fd #include <sys/socket.h> -.Fd #include <netinet/in.h> -.Fd #include <netinet/icmp6.h> -.Ft int -.Fn socket AF_INET6 SOCK_RAW proto -.Sh DESCRIPTION -.Tn ICMPv6 -is the error and control message protocol used -by -.Tn IPv6 -and the Internet protocol family. -It may be accessed through a -.Dq raw socket -for network monitoring and diagnostic functions. -The -.Fa proto -parameter to the socket call to create an -.Tn ICMPv6 -socket is obtained from -.Xr getprotobyname 3 , -or you can use -.Dv IPPROTO_ICMPV6 . -.Tn ICMPv6 -sockets are connectionless, and are normally used with the -.Xr sendto 2 -and -.Xr recvfrom 2 -calls, though the -.Xr connect 2 -call may also be used to fix the destination for future packets -(in which case the -.Xr read 2 -or -.Xr recv 2 -and -.Xr write 2 -or -.Xr send 2 -system calls may be used). -.Pp -Outgoing packets automatically have an -.Tn IPv6 -header prepended to them -.Pq based on the destination address . -The -.Tn ICMPv6 -pseudo-header checksum field -.Pq Li icmp6_cksum -is filled automatically by the kernel. -Incoming packets are received without the -.Tn IPv6 -header or IPv6 extension headers. -Notice that this behavior is opposite to that of -.Tn IPv4 -raw sockets and -.Tn ICMPv4 -sockets. -.Ss ICMPv6 type/code filter -Each -.Tn ICMPv6 -raw socket has an associated filter whose datatype is defined as -.Li struct icmp6_filter ; -.Pp -This structure, along with the macros and constants defined later in -this section, are defined as a result of including the -.Aq Li netinet/icmp6.h -header. -.Pp -The current filter is fetched and stored using -.Xr getsockopt 2 -and -.Xr setsockopt 2 -with a level of -.Dv IPPROTO_ICMPV6 -and an option name of -.Dv ICMP6_FILTER . -.Pp -Six macros operate on an icmp6_filter structure: -.\" is "Fn" legal for macros? -.Pp -.Bl -item -compact -offset indent -.It -.Ft void -.Fn ICMP6_FILTER_SETPASSALL "struct icmp6_filter *" -.It -.Ft void -.Fn ICMP6_FILTER_SETBLOCKALL "struct icmp6_filter *" -.It -.Ft void -.Fn ICMP6_FILTER_SETPASS "int" "struct icmp6_filter *" -.It -.Ft void -.Fn ICMP6_FILTER_SETBLOCK "int" "struct icmp6_filter *" -.It -.Ft int -.Fn ICMP6_FILTER_WILLPASS "int" "const struct icmp6_filter *" -.It -.Ft int -.Fn ICMP6_FILTER_WILLBLOCK "int" "const struct icmp6_filter *" -.El -.Pp -The first argument to the last four macros -.Pq an integer -is an -.Tn ICMPv6 -message type, between 0 and 255. -The pointer argument to all six -macros is a pointer to a filter that is modified by the first four -macros examined by the last two macros. -.Pp -The first two macros, -.Dv SETPASSALL -and -.Dv SETBLOCKALL , -specify that all -.Tn ICMPv6 -messages are passed to the application or that all -.Tn ICMPv6 -messages are blocked from being passed to the application. -.Pp -The next two macros, -.Dv SETPASS -and -.Dv SETBLOCK , -specify that messages of a given -.Tn ICMPv6 -type should be passed to the application -or not passed to the application -.Pq blocked . -.Pp -The final two macros, -.Dv WILLPASS -and -.Dv WILLBLOCK , -return true or false -depending on whether the specified message type is passed to the -application or blocked from being passed to the application by the -filter pointed to by the second argument. -.Pp -When an -.Tn ICMPv6 -raw socket is created, it will by default pass all -.Tn ICMPv6 -message types to the application. -.Pp -For further discussions see RFC 2292. -.Sh DIAGNOSTICS -A socket operation may fail with one of the following errors returned: -.Bl -tag -width [EADDRNOTAVAIL] -.It Bq Er EISCONN -when trying to establish a connection on a socket which -already has one, or when trying to send a datagram with the destination -address specified and the socket is already connected. -.It Bq Er ENOTCONN -when trying to send a datagram, but -no destination address is specified, and the socket hasn't been -connected. -.It Bq Er ENOBUFS -when the system runs out of memory for -an internal data structure. -.It Bq Er EADDRNOTAVAIL -when an attempt is made to create a -socket with a network address for which no network interface exists. -.El -.Sh SEE ALSO -.Xr recv 2 , -.Xr send 2 , -.Xr inet6 4 , -.Xr ip6 4 , -.Xr netintro 4 -.Rs -.%A W. Stevens -.%A M. Thomas -.%R RFC 2292 -.%D February 1998 -.%T "Advanced Sockets API for IPv6" -.Re -.Rs -.%A A. Conta -.%A S. Deering -.%R RFC 2463 -.%D December 1998 -.%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification" -.Re -.Sh HISTORY -The implementation is based on KAME stack -.Po -which is a descendant of WIDE hydrangea IPv6 stack kit -.Pc . -.Pp -Part of the document was shamelessly copied from RFC 2292. diff --git a/share/man/man4/ip6.4 b/share/man/man4/ip6.4 deleted file mode 100644 index 01c57a7effb..00000000000 --- a/share/man/man4/ip6.4 +++ /dev/null @@ -1,658 +0,0 @@ -.\" $OpenBSD: ip6.4,v 1.16 2003/08/08 09:51:53 jmc Exp $ -.\" $KAME: ip6.4,v 1.12 2000/06/08 21:19:39 itojun Exp $ -.\" -.\" Copyright (C) 1999 WIDE Project. -.\" 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 project 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 PROJECT 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 PROJECT 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. -.\" -.\" Copyright (c) 1983, 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 17, 1999 -.Dt IP6 4 -.Os -.Sh NAME -.Nm ip6 -.Nd Internet Protocol version 6 (IPv6) -.Sh SYNOPSIS -.Fd #include <sys/socket.h> -.Fd #include <netinet/in.h> -.Ft int -.Fn socket AF_INET6 SOCK_RAW proto -.Sh DESCRIPTION -.Tn IPv6 -is the network layer protocol used by the Internet protocol version 6 family -.Pq Dv AF_INET6 . -Options may be set at the -.Tn IPv6 -level when using higher-level protocols that are based on -.Tn IPv6 -(such as -.Tn TCP -and -.Tn UDP ) . -It may also be accessed through a -.Dq raw socket -when developing new protocols, or special-purpose applications. -.Pp -There are several -.Tn IPv6-level -.Xr setsockopt 2 / Ns Xr getsockopt 2 -options. -They are separated into the basic IPv6 sockets API -.Pq defined in RFC 2553 , -and the advanced API -.Pq defined in RFC 2292 . -The basic API looks very similar to the API presented in -.Xr ip 4 . -Advanced API uses ancillary data and can handle more complex cases. -.Pp -To specify some socket options, a certain level of privilege -(i.e. root privilege) is required. -.\" -.Ss Basic IPv6 sockets API -.Dv IPV6_UNICAST_HOPS -may be used to set the hoplimit field in the -.Tn IPv6 -header. -As the symbol name suggests, the option controls the hoplimit field -on unicast packets. -If -1 is specified, the kernel will use a default value. -If a value of 0 to 255 is specified, the packet will have the specified -value as hoplimit. -Other values are considered invalid, and -.Dv EINVAL -will be returned. -For example: -.Bd -literal -offset indent -int hlim = 60; /* max = 255 */ -setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, &hlim, sizeof(hlim)); -.Ed -.Pp -.Tn IPv6 -multicasting is supported only on -.Dv AF_INET6 -sockets of type -.Dv SOCK_DGRAM -and -.Dv SOCK_RAW , -and only on networks where the interface driver supports multicasting. -.Pp -The -.Dv IPV6_MULTICAST_HOPS -option changes the hoplimit for outgoing multicast datagrams -in order to control the scope of the multicasts: -.Bd -literal -offset indent -unsigned int hlim; /* range: 0 to 255, default = 1 */ -setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_HOPS, &hlim, sizeof(hlim)); -.Ed -.Pp -Datagrams with a hoplimit of 1 are not forwarded beyond the local network. -Multicast datagrams with a hoplimit of 0 will not be transmitted on any network, -but may be delivered locally if the sending host belongs to the destination -group and if multicast loopback has not been disabled on the sending socket -(see below). -Multicast datagrams with a hoplimit greater than 1 may be forwarded -to other networks if a multicast router is attached to the local network. -.Pp -For hosts with multiple interfaces, each multicast transmission is -sent from the primary network interface. -The -.Dv IPV6_MULTICAST_IF -option overrides the default for -subsequent transmissions from a given socket: -.Bd -literal -offset indent -unsigned int outif; -outif = if_nametoindex("ne0"); -setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_IF, &outif, sizeof(outif)); -.Ed -.Pp -where "outif" is an interface index of the desired interface, -or 0 to specify the default interface. -.Pp -If a multicast datagram is sent to a group to which the sending host itself -belongs (on the outgoing interface), a copy of the datagram is, by default, -looped back by the IPv6 layer for local delivery. -The -.Dv IPV6_MULTICAST_LOOP -option gives the sender explicit control -over whether or not subsequent datagrams are looped back: -.Bd -literal -offset indent -u_char loop; /* 0 = disable, 1 = enable (default) */ -setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_LOOP, &loop, sizeof(loop)); -.Ed -.Pp -This option -improves performance for applications that may have no more than one -instance on a single host (such as a router daemon), by eliminating -the overhead of receiving their own transmissions. -It should generally not be used by applications for which there -may be more than one instance on a single host (such as a conferencing -program) or for which the sender does not belong to the destination -group (such as a time querying program). -.Pp -A multicast datagram sent with an initial hoplimit greater than 1 may be -delivered to the sending host on a different interface from that on which -it was sent, if the host belongs to the destination group on that other -interface. -The loopback control option has no effect on such delivery. -.Pp -A host must become a member of a multicast group before it can receive -datagrams sent to the group. -To join a multicast group, use the -.Dv IPV6_JOIN_GROUP -option: -.Bd -literal -offset indent -struct ipv6_mreq mreq6; -setsockopt(s, IPPROTO_IPV6, IPV6_JOIN_GROUP, &mreq6, sizeof(mreq6)); -.Ed -.Pp -where -.Fa mreq6 -is the following structure: -.Bd -literal -offset indent -struct ipv6_mreq { - struct in6_addr ipv6mr_multiaddr; - unsigned int ipv6mr_interface; -}; -.Ed -.Pp -.Dv ipv6mr_interface -should be 0 to choose the default multicast interface, or the -interface index of a particular multicast-capable interface if -the host is multihomed. -Membership is associated with a single interface; -programs running on multihomed hosts may need to -join the same group on more than one interface. -.Pp -To drop a membership, use: -.Bd -literal -offset indent -struct ipv6_mreq mreq6; -setsockopt(s, IPPROTO_IPV6, IPV6_LEAVE_GROUP, &mreq6, sizeof(mreq6)); -.Ed -.Pp -where -.Fa mreq6 -contains the same values as used to add the membership. -Memberships are dropped when the socket is closed or the process exits. -.Pp -.Dv IPV6_PORTRANGE -controls how ephemeral ports are allocated for -.Dv SOCK_STREAM -and -.Dv SOCK_DGRAM -sockets. -For example, -.Bd -literal -offset indent -int range = IPV6_PORTRANGE_LOW; /* see <netinet/in.h> */ -setsockopt(s, IPPROTO_IPV6, IPV6_PORTRANGE, &range, sizeof(range)); -.Ed -.\" -.Ss Advanced IPv6 sockets API -The advanced IPv6 sockets API lets userland programs specify or obtain -details about the IPv6 header and the IPv6 extension headers on packets. -The advanced API uses ancillary data for passing data from/to the kernel. -.Pp -There are -.Xr setsockopt 2 / Ns Xr getsockopt 2 -options to get optional information on incoming packets. -They are -.Dv IPV6_PKTINFO , -.Dv IPV6_HOPLIMIT , -.Dv IPV6_HOPOPTS , -.Dv IPV6_DSTOPTS , -and -.Dv IPV6_RTHDR . -.Bd -literal -offset indent -int on = 1; - -setsockopt(fd, IPPROTO_IPV6, IPV6_PKTINFO, &on, sizeof(on)); -setsockopt(fd, IPPROTO_IPV6, IPV6_HOPLIMIT, &on, sizeof(on)); -setsockopt(fd, IPPROTO_IPV6, IPV6_HOPOPTS, &on, sizeof(on)); -setsockopt(fd, IPPROTO_IPV6, IPV6_DSTOPTS, &on, sizeof(on)); -setsockopt(fd, IPPROTO_IPV6, IPV6_RTHDR, &on, sizeof(on)); -.Ed -.Pp -When any of these options are enabled, the corresponding data is -returned as control information by -.Xr recvmsg 2 , -as one or more ancillary data objects. -.Pp -If -.Dv IPV6_PKTINFO -is enabled, the destination IPv6 address and the arriving interface index -will be available via -.Li struct in6_pktinfo -on ancillary data stream. -You can pick the structure by checking for an ancillary data item with -.Li cmsg_level -equal to -.Dv IPPROTO_IPV6 , -and -.Li cmsg_type -equal to -.Dv IPV6_PKTINFO . -.Pp -If -.Dv IPV6_HOPLIMIT -is enabled, the hoplimit value on the packet will be made available to the -userland program. -The ancillary data stream will contain an integer data item with -.Li cmsg_level -equal to -.Dv IPPROTO_IPV6 , -and -.Li cmsg_type -equal to -.Dv IPV6_HOPLIMIT . -.Pp -.Xr inet6_option_space 3 -and friends help parse ancillary data items for -.Dv IPV6_HOPOPTS -and -.Dv IPV6_DSTOPTS . -Similarly, -.Xr inet6_rthdr_space 3 -and friends help parse ancillary data items for -.Dv IPV6_RTHDR . -.Pp -.Dv IPV6_HOPOPTS -and -.Dv IPV6_DSTOPTS -may appear multiple times on an ancillary data stream -(note that the behavior is slightly different than the specification). -Other ancillary data items can appear no more than once. -.Pp -For outgoing direction, -ancillary data items with normal payload data can be passed using -.Xr sendmsg 2 . -Ancillary data items will be parsed by the kernel, and used to construct -the IPv6 header and extension headers. -For the 5 -.Li cmsg_level -values listed above, the ancillary data format is the same as the inbound case. -Additionally, the -.Dv IPV6_NEXTHOP -data object can also be specified. -The -.Dv IPV6_NEXTHOP -ancillary data object specifies the next hop for the -datagram as a socket address structure. -In the -.Li cmsghdr -structure -containing this ancillary data, the -.Li cmsg_level -member will be -.Dv IPPROTO_IPV6 , -the -.Li cmsg_type -member will be -.Dv IPV6_NEXTHOP , -and the first byte of -.Li cmsg_data[] -will be the first byte of the socket address structure. -.Pp -If the socket address structure contains an IPv6 address (i.e., the -sin6_family member is -.Dv AF_INET6 -), then the node identified by that -address must be a neighbor of the sending host. -If that address -equals the destination IPv6 address of the datagram, then this is -equivalent to the existing -.Dv SO_DONTROUTE -socket option. -.Pp -For applications that do not, or are unable to use -.Xr sendmsg 2 -or -.Xr recvmsg 2 , -the -.Dv IPV6_PKTOPTIONS -socket option is defined. -Setting the socket option specifies any of the optional output fields: -.Bd -literal -offset indent -setsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, len); -.Ed -.Pp -The fourth argument points to a buffer containing one or more -ancillary data objects, and the fifth argument is the total length of -all these objects. -The application fills in this buffer exactly as -if the buffer were being passed to -.Xr sendmsg 2 -as control information. -.Pp -The options set by calling -.Xr setsockopt 2 -for -.Dv IPV6_PKTOPTIONS -are -called "sticky" options because once set they apply to all packets -sent on that socket. -The application can call -.Xr setsockopt 2 -again to -change all the sticky options, or it can call -.Xr setsockopt 2 -with a -length of 0 to remove all the sticky options for the socket. -.Pp -The corresponding receive option -.Bd -literal -offset indent -getsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, &len); -.Ed -.Pp -returns a buffer with one or more ancillary data objects for all the -optional receive information that the application has previously -specified that it wants to receive. -The fourth argument points to -the buffer that is filled in by the call. -The fifth argument is a -pointer to a value-result integer: when the function is called the -integer specifies the size of the buffer pointed to by the fourth -argument, and on return this integer contains the actual number of -bytes that were returned. -The application processes this buffer -exactly as if the buffer were returned by -.Xr recvmsg 2 -as control information. -.\" -.Ss Advanced API and TCP sockets -When using -.Xr getsockopt 2 -with the -.Dv IPV6_PKTOPTIONS -option and a -.Tn TCP -socket, only the options from the most recently received segment are -retained and returned to the caller, and only after the socket option -has been set. -.\" That is, -.\" .Tn TCP -.\" need not start saving a copy of the options until the application says -.\" to do so. -The application is not allowed to specify ancillary data in a call to -.Xr sendmsg 2 -on a -.Tn TCP -socket, and none of the ancillary data that we -described above is ever returned as control information by -.Xr recvmsg 2 -on a -.Tn TCP -socket. -.\" -.Ss Conflict resolution -In some cases, there are multiple APIs defined for manipulating -a IPv6 header field. -A good example is the outgoing interface for multicast datagrams: -it can be manipulated by -.Dv IPV6_MULTICAST_IF -in basic API, -.Dv IPV6_PKTINFO -in advanced API, and the -.Li sin6_scope_id -field of the socket address passed to -.Xr sendto 2 . -.Pp -When conflicting options are given to the kernel, -the kernel will get the value in the following order of preference: -(1) options specified by using ancillary data, -(2) options specified by a sticky option of the advanced API, -(3) options specified by using the basic API, and lastly -(4) options specified by a socket address. -Note that the conflict resolution is undefined in the API specification -and implementation dependent. -.\" -.Ss "Raw IPv6 Sockets" -Raw -.Tn IPv6 -sockets are connectionless, and are normally used with the -.Xr sendto 2 -and -.Xr recvfrom 2 -calls, though the -.Xr connect 2 -call may also be used to fix the destination for future -packets (in which case the -.Xr read 2 -or -.Xr recv 2 -and -.Xr write 2 -or -.Xr send 2 -system calls may be used). -.Pp -If -.Fa proto -is 0, the default protocol -.Dv IPPROTO_RAW -is used for outgoing packets, and only incoming packets destined -for that protocol are received. -If -.Fa proto -is non-zero, that protocol number will be used on outgoing packets -and to filter incoming packets. -.Pp -Outgoing packets automatically have an -.Tn IPv6 -header prepended to them (based on the destination address and the -protocol number the socket is created with). -Incoming packets are received without an -.Tn IPv6 -header or extension headers. -.Pp -All data sent via raw sockets MUST be in network byte order and all -data received via raw sockets will be in network byte order. -This differs from the IPv4 raw sockets, which did not specify a byte -ordering and typically used the host's byte order. -.Pp -Another difference from IPv4 raw sockets is that complete packets -(that is, IPv6 packets with extension headers) cannot be read or -written using the IPv6 raw sockets API. -Instead, ancillary data -objects are used to transfer the extension headers, as described above. -Should an application need access to the -complete IPv6 packet, some other technique, such as the datalink -interfaces, such as -.Xr bpf 4 , -must be used. -.Pp -All fields in the IPv6 header that an application might want to -change (i.e., everything other than the version number) can be -modified using ancillary data and/or socket options by the -application for output. -All fields in a received IPv6 header (other -than the version number and Next Header fields) and all extension -headers are also made available to the application as ancillary data -on input. -Hence there is no need for a socket option similar to the -IPv4 -.Dv IP_HDRINCL -socket option. -.Pp -When writing to a raw socket the kernel will automatically fragment -the packet if its size exceeds the path MTU, inserting the required -fragmentation headers. -On input the kernel reassembles received fragments, so the reader -of a raw socket never sees any fragment headers. -.Pp -Most IPv4 implementations give special treatment to a raw socket -created with a third argument to -.Xr socket 2 -of -.Dv IPPROTO_RAW , -whose value is normally 255. -We note that this value has no special meaning to -an IPv6 raw socket (and the IANA currently reserves the value of 255 -when used as a next-header field). -.\" Note: This feature was added to -.\" IPv4 in 1988 by Van Jacobson to support traceroute, allowing a -.\" complete IP header to be passed by the application, before the -.\" .Dv IP_HDRINCL -.\" socket option was added. -.Pp -For ICMPv6 raw sockets, -the kernel will calculate and insert the ICMPv6 checksum -since this checksum is mandatory. -.Pp -For other raw IPv6 sockets (that is, for raw IPv6 sockets created -with a third argument other than IPPROTO_ICMPV6), the application -must set the new IPV6_CHECKSUM socket option to have the kernel (1) -compute and store a pseudo-header checksum for output, -and (2) verify the received -pseudo-header checksum on input, -discarding the packet if the checksum is in error. -This option prevents applications from having to perform source -address selection on the packets they send. -The checksum will -incorporate the IPv6 pseudo-header, defined in Section 8.1 of RFC 2460. -This new socket option also specifies an integer offset into -the user data of where the checksum is located. -.Bd -literal -offset indent -int offset = 2; -setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, sizeof(offset)); -.Ed -.Pp -By default, this socket option is disabled. -Setting the offset to -1 also disables the option. -By disabled we mean (1) the kernel will -not calculate and store a checksum for outgoing packets, and (2) the -kernel will not verify a checksum for received packets. -.Pp -Note: Since the checksum is always calculated by the kernel for an -ICMPv6 socket, applications are not able to generate ICMPv6 packets -with incorrect checksums (presumably for testing purposes) using this -API. -.\" -.Sh DIAGNOSTICS -A socket operation may fail with one of the following errors returned: -.Bl -tag -width [EADDRNOTAVAIL] -.It Bq Er EISCONN -when trying to establish a connection on a socket which already -has one, or when trying to send a datagram with the destination -address specified and the socket is already connected. -.It Bq Er ENOTCONN -when trying to send a datagram, but no destination address is -specified, and the socket hasn't been connected. -.It Bq Er ENOBUFS -when the system runs out of memory for an internal data structure. -.It Bq Er EADDRNOTAVAIL -when an attempt is made to create a socket with a network address -for which no network interface exists. -.It Bq Er EACCES -when an attempt is made to create a raw IPv6 socket by a non-privileged process. -.El -.Pp -The following errors specific to -.Tn IPv6 -may occur: -.Bl -tag -width EADDRNOTAVAILxx -.It Bq Er EINVAL -An unknown socket option name was given. -.It Bq Er EINVAL -The ancillary data items were improperly formed, or option name was unknown. -.El -.\" -.Sh SEE ALSO -.Xr getsockopt 2 , -.Xr recv 2 , -.Xr send 2 , -.Xr setsockopt 2 , -.Xr inet6_option_space 3 , -.Xr inet6_rthdr_space 3 , -.Xr icmp6 4 , -.Xr inet6 4 -.Rs -.%A W. Stevens -.%A M. Thomas -.%R RFC 2292 -.%D February 1998 -.%T "Advanced Sockets API for IPv6" -.Re -.Rs -.%A S. Deering -.%A R. Hinden -.%R RFC 2460 -.%D December 1998 -.%T "Internet Protocol, Version 6 (IPv6) Specification" -.Re -.Rs -.%A R. Gilligan -.%A S. Thomson -.%A J. Bound -.%A W. Stevens -.%R RFC 2553 -.%D March 1999 -.%T "Basic Socket Interface Extensions for IPv6" -.Re -.\" -.Sh STANDARDS -Most of the socket options are defined in -RFC 2292 and/or RFC 2553. -.Dv IPV6_PORTRANGE -and conflict resolution rule -is not defined in the RFCs and should be considered implementation dependent. -.\" -.Sh HISTORY -The implementation is based on KAME stack -.Po -which is a descendant of WIDE hydrangea IPv6 stack kit -.Pc . -.Pp -Part of the document was shamelessly copied from RFC 2553 and RFC 2292. -.\" -.Sh BUGS -The -.Dv IPV6_NEXTHOP -object/option is not fully implemented as of writing this. |