diff options
| -rw-r--r-- | lib/libc/net/Makefile.inc | 4 | ||||
| -rw-r--r-- | lib/libc/net/getaddrinfo.3 | 632 | ||||
| -rw-r--r-- | lib/libc/net/getnameinfo.3 | 311 | ||||
| -rw-r--r-- | lib/libc/net/inet6_opt_init.3 | 319 | ||||
| -rw-r--r-- | lib/libc/net/inet6_option_space.3 | 485 | ||||
| -rw-r--r-- | lib/libc/net/inet6_rth_space.3 | 273 | ||||
| -rw-r--r-- | lib/libc/net/inet6_rthdr_space.3 | 335 | ||||
| -rw-r--r-- | share/man/man4/icmp6.4 | 267 | ||||
| -rw-r--r-- | share/man/man4/ip6.4 | 710 |
9 files changed, 2 insertions, 3334 deletions
diff --git a/lib/libc/net/Makefile.inc b/lib/libc/net/Makefile.inc index 9b94ed3..a20daef 100644 --- a/lib/libc/net/Makefile.inc +++ b/lib/libc/net/Makefile.inc @@ -40,7 +40,7 @@ nslexer.c: nslexer.l nsparser.h .endif MAN+= addr2ascii.3 byteorder.3 ethers.3 eui64.3 \ - getaddrinfo.3 gethostbyname.3 \ + getaddrinfo.3 gai_strerror.3 gethostbyname.3 \ getifaddrs.3 getifmaddrs.3 getipnodebyname.3 \ getnameinfo.3 getnetent.3 getprotoent.3 getservent.3 hesiod.3 \ if_indextoname.3 \ @@ -56,7 +56,7 @@ MLINKS+=ethers.3 ether_aton.3 ethers.3 ether_hostton.3 ethers.3 ether_line.3 \ ethers.3 ether_ntoa.3 ethers.3 ether_ntohost.3 MLINKS+=eui64.3 eui64_aton.3 eui64.3 eui64_hostton.3 \ eui64.3 eui64_ntoa.3 eui64.3 eui64_ntohost.3 -MLINKS+=getaddrinfo.3 freeaddrinfo.3 getaddrinfo.3 gai_strerror.3 +MLINKS+=getaddrinfo.3 freeaddrinfo.3 getaddrinfo.3 MLINKS+=gethostbyname.3 endhostent.3 gethostbyname.3 gethostbyaddr.3 \ gethostbyname.3 gethostbyname2.3 gethostbyname.3 gethostent.3 \ gethostbyname.3 herror.3 gethostbyname.3 hstrerror.3 \ diff --git a/lib/libc/net/getaddrinfo.3 b/lib/libc/net/getaddrinfo.3 deleted file mode 100644 index e72fb25..0000000 --- a/lib/libc/net/getaddrinfo.3 +++ /dev/null @@ -1,632 +0,0 @@ -.\" $KAME: getaddrinfo.3,v 1.31 2001/08/05 18:19:38 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. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. 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 -.\" $FreeBSD$ -.\" -.Dd August 6, 2004 -.Dt GETADDRINFO 3 -.Os -.\" -.Sh NAME -.Nm getaddrinfo , -.Nm freeaddrinfo , -.Nm gai_strerror -.Nd nodename-to-address translation in protocol-independent manner -.\" -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In sys/types.h -.In sys/socket.h -.In 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" -.Ft "char *" -.Fn gai_strerror "int ecode" -.\" -.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 -The -.Li addrinfo -structure is defined as a result of including the -.In netdb.h -header: -.Bd -literal -offset -struct addrinfo { - int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ - int ai_family; /* PF_xxx */ - int ai_socktype; /* SOCK_xxx */ - int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ - size_t ai_addrlen; /* length of ai_addr */ - char *ai_canonname; /* canonical name for nodename */ - struct sockaddr *ai_addr; /* binary address */ - struct addrinfo *ai_next; /* next structure in linked list */ -}; -.Ed -.Pp -The -.Fa nodename -and -.Fa servname -arguments are pointers to null-terminated strings or -.Dv NULL . -One or both of these two arguments must be a -.Pf non Dv -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 -.Pf non Dv -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 -.Pf non Dv -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 -.Dv 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 -.Dv 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 -.Dv 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 -.Fn socket -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 -If the -.Dv AI_PASSIVE -bit is set in the -.Fa ai_flags -member of the -.Fa hints -structure, then the caller plans to use the returned socket address -structure in a call to -.Fn bind . -In this case, if the -.Fa nodename -argument is a -.Dv 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 in the -.Fa ai_flags -member of the -.Fa hints -structure, then the returned socket address structure will be ready for a -call to -.Fn connect -(for a connection-oriented protocol) -or either -.Fn connect , -.Fn sendto , -or -.Fn sendmsg -(for a connectionless protocol). -In this case, if the -.Fa nodename -argument is a -.Dv NULL -pointer, then the IP address portion of the -socket address structure will be set to the loopback address. -.Pp -If the -.Dv AI_CANONNAME -bit is set in the -.Fa ai_flags -member of the -.Fa hints -structure, then upon successful return the -.Fa ai_canonname -member of the first -.Li addrinfo -structure in the linked list will point to a null-terminated string -containing the canonical name of the specified -.Fa nodename . -.Pp -If the -.Dv AI_NUMERICHOST -bit is set in the -.Fa ai_flags -member of the -.Fa hints -structure, then a -.Pf non Dv -NULL -.Fa nodename -string must be a numeric host address string. -Otherwise an error of -.Dv EAI_NONAME -is returned. -This flag prevents any type of name resolution service (e.g., the DNS) -from being called. -.Pp -The arguments to -.Fn getaddrinfo -must be sufficiently consistent and unambiguous. -Here are some problem cases you may encounter: -.Bl -bullet -.It -The -.Fn getaddrinfo -function -will fail if the members in the -.Fa hints -structure are not consistent. -For example, for internet address families, -.Fn getaddrinfo -will fail 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 fail because the arguments are not consistent. -For example, -.Fn getaddrinfo -will return 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 fail, because service names are not defined for the internet -.Dv SOCK_RAW -space. -.It -If you specify numeric -.Fa servname , -while leaving -.Fa ai_socktype -and -.Fa ai_protocol -unspecified, -.Fn getaddrinfo -will fail. -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 -.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 -.Vt addrinfo -structure pointed to by the -.Fa ai -argument -is freed, along with any dynamic storage pointed to by the structure. -This operation is repeated until a -.Dv NULL -.Fa ai_next -pointer is encountered. -.Pp -To aid applications in printing error messages based on the -.Dv EAI_xxx -codes returned by -.Fn getaddrinfo , -.Fn gai_strerror -is defined. -The argument is one of the -.Dv EAI_xxx -values defined earlier and the return value points to a string describing -the error. -If the argument is not one of the -.Dv EAI_xxx -values, the function still returns a pointer to a string whose contents -indicate an unknown error. -.\" -.Sh EXTENSIONS -This implementation supports numeric IPv6 address notation with the -experimental scope identifier. -By appending a percent sign and scope identifier to the address, you -can specify the value of the -.Li sin6_scope_id -field of the socket address. -This makes management of scoped address easier, -and allows cut-and-paste input of scoped addresses. -.Pp -At the moment the code supports only link-local addresses in this format. -The scope identifier is hardcoded to name of hardware interface associated -with the link, -(such as -.Li ne0 ) . -For example, -.Dq Li fe80::1%ne0 , -which means -.Do -.Li fe80::1 -on the link associated with the -.Li ne0 -interface -.Dc . -.Pp -This implementation is still very experimental and non-standard. -The current implementation assumes a one-to-one relationship between -interfaces and links, which is not necessarily true according to the -specification. -.\" -.Sh FILES -.Bl -tag -width /etc/nsswitch.conf -compact -.It Pa /etc/hosts -.It Pa /etc/nsswitch.conf -.It Pa /etc/resolv.conf -.El -.\" -.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 the address family. -If the destination resolves to an IPv4 address, it will use an -.Dv AF_INET -socket. -Similarly, if it resolves to IPv6, an -.Dv AF_INET6 -socket is used. -Observe that there is no hardcoded reference to particular address family. -The code works even if -.Fn 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; -cause = "no addresses"; -errno = EADDRNOTAVAIL; -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, 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; - } - - if (listen(s[nsock], SOMAXCONN) < 0) { - cause = "listen"; - close(s[nsock]); - continue; - } - - nsock++; -} -if (nsock == 0) { - err(1, cause); - /*NOTREACHED*/ -} -freeaddrinfo(res0); -.Ed -.\" -.Sh DIAGNOSTICS -Error return status from -.Fn getaddrinfo -is zero on success and non-zero on errors. -Non-zero error codes are defined in -.In netdb.h , -and as follows: -.Pp -.Bl -tag -width EAI_ADDRFAMILY -compact -.It Dv EAI_AGAIN -Temporary failure in name resolution. -.It Dv EAI_BADFLAGS -Invalid value for -.Fa ai_flags . -.It Dv EAI_FAIL -Non-recoverable failure in name resolution. -.It Dv EAI_FAMILY -The -.Fa ai_family -address family is -not supported. -.It Dv EAI_MEMORY -Memory allocation failure. -.It Dv EAI_NONAME -Neither -.Fa nodename -nor -.Fa servname -provided, or not known. -.It Dv EAI_SERVICE -The -.Fa servname -service name is -not supported for -.Fa ai_socktype . -.It Dv EAI_SOCKTYPE -The -.Fa ai_socktype -socket type is -not supported. -.It Dv EAI_SYSTEM -System error returned in -.Va errno . -.It Dv EAI_BADHINTS -Invalid value for -.Fa hints . -.It Dv EAI_PROTOCOL -Resolved protocol is unknown. -.It Dv EAI_MAX -Unknown error. -.El -.Pp -If called with an appropriate argument, -.Fn gai_strerror -returns a pointer to a string describing the given error code. -If the argument is not one of the -.Dv EAI_xxx -values, the function still returns a pointer to a string whose contents -indicate an unknown error. -.\" -.Sh SEE ALSO -.Xr gethostbyname 3 , -.Xr getipnodebyname 3 , -.Xr getnameinfo 3 , -.Xr getservbyname 3 , -.Xr hosts 5 , -.Xr resolv.conf 5 , -.Xr services 5 , -.Xr hostname 7 , -.Xr named 8 -.Pp -.Rs -.%A R. Gilligan -.%A S. Thomson -.%A J. Bound -.%A W. Stevens -.%T Basic Socket Interface Extensions for IPv6 -.%R RFC2553 -.%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 getaddrinfo -function is defined in -.St -p1003.1g-2000 , -and documented in -.Dq Basic Socket Interface Extensions for IPv6 -(RFC2553). -.\" -.Sh HISTORY -The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. -.\" -.Sh BUGS -Although the current implementation is otherwise thread-safe, using -.Fn getaddrinfo -in conjunction with -.Fn gethostby* -(see -.Xr gethostbyname 3 ) -or -.Xr yp 8 -breaks the thread-safety of both. -.Pp -The text was shamelessly copied from RFC2553. diff --git a/lib/libc/net/getnameinfo.3 b/lib/libc/net/getnameinfo.3 deleted file mode 100644 index 5691815..0000000 --- a/lib/libc/net/getnameinfo.3 +++ /dev/null @@ -1,311 +0,0 @@ -.\" $FreeBSD$ -.\" $KAME: getnameinfo.3,v 1.17 2000/08/09 21:16:17 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. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. 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 August 6, 2004 -.Dt GETNAMEINFO 3 -.Os -.\" -.Sh NAME -.Nm getnameinfo -.Nd address-to-nodename translation in protocol-independent manner -.\" -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In sys/types.h -.In sys/socket.h -.In 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 with -.Xr gethostbyaddr 3 -and -.Xr getservbyport 3 -in 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 -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 -.In netdb.h : -.Bd -literal -offset -#define NI_MAXHOST 1025 -#define NI_MAXSERV 32 -.Ed -.Pp -The first value is actually defined as the constant -.Dv MAXDNAME -in recent versions of BIND's -.In 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. -By default the fully-qualified domain name (FQDN) for the host is -looked up in the DNS and returned. -If the flag bit -.Dv NI_NOFQDN -is set, only the nodename portion of the FQDN is returned for local hosts. -.Pp -If the -.Fa flag -bit -.Dv NI_NUMERICHOST -is set, or if the host's name cannot be located in the DNS, -the numeric form of the host's address is returned instead of its name -(e.g., by calling -.Fn inet_ntop -instead of -.Fn getnodebyaddr ) . -If the -.Fa flag -bit -.Dv NI_NAMEREQD -is set, an error is returned if the host's name cannot be located in the DNS. -.Pp -If the flag bit -.Dv NI_NUMERICSERV -is set, the numeric form of the service address is returned -(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. -.Pp -A fifth flag bit, -.Dv NI_DGRAM , -specifies that the service is a datagram service, and causes -.Fn getservbyport -to be called with a second argument of -.Dq udp -instead of its default of -.Dq tcp . -This is required for the few ports (512-514) -that have different services for UDP and TCP. -.Pp -These -.Dv NI_xxx -flags are defined in -.In netdb.h . -.\" -.Ss Extension for scoped IPv6 address -The implementation allows experimental numeric IPv6 address notation with -scope identifier. -IPv6 link-local address will appear as a string like -.Dq Li fe80::1%ne0 . -Refer to -.Xr getaddrinfo 3 -for the notation. -.\" -.Sh FILES -.Bl -tag -width /etc/nsswitch.conf -compact -.It Pa /etc/hosts -.It Pa /etc/nsswitch.conf -.It Pa /etc/resolv.conf -.El -.\" -.Sh EXAMPLES -The following code tries to get numeric hostname, and service name, -for given socket address. -Observe that there is no hardcoded reference to 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\\n", 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\\n", hbuf); -.Ed -.\" -.Sh DIAGNOSTICS -The function indicates successful completion by a zero return value; -a non-zero return value indicates failure. -Error codes are as below: -.Bl -tag -width Er -.It Bq Er EAI_AGAIN -The name could not be resolved at this time. -Future attempts may succeed. -.It Bq Er EAI_BADFLAGS -The flags had an invalid value. -.It Bq Er EAI_FAIL -A non-recoverable error occurred. -.It Bq Er EAI_FAMILY -The address family was not recognized or the address length was invalid -for the specified family. -.It Bq Er EAI_MEMORY -There was a memory allocation failure. -.It Bq Er EAI_NONAME -The name does not resolve for the supplied arguments. -.Dv NI_NAMEREQD -is set and the host's name cannot be located, -or both nodename and servname were null. -.It Bq Er EAI_SYSTEM -A system error occurred. -The error code can be found in errno. -.El -.\" -.Sh SEE ALSO -.Xr getaddrinfo 3 , -.Xr gethostbyaddr 3 , -.Xr getipnodebyaddr 3 , -.Xr getservbyport 3 , -.Xr hosts 5 , -.Xr services 5 , -.Xr hostname 7 , -.Xr named 8 -.Pp -.Rs -.%A R. Gilligan -.%A S. Thomson -.%A J. Bound -.%A W. Stevens -.%T Basic Socket Interface Extensions for IPv6 -.%R RFC2553 -.%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 getaddrinfo -function is defined in -.St -p1003.1g-2000 , -and documented in -.Dq Basic Socket Interface Extensions for IPv6 -(RFC2553). -.\" -.Sh HISTORY -The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. -.\" -.Sh BUGS -Though the current implementation should be thread-safe, using -.Fn getnameinfo -in conjunction with -.Fn gethostby* -breaks thread-safeness. -.Pp -The text was shamelessly copied from RFC2553. -.Pp -The type of the 2nd argument should be -.Li socklen_t -for RFC2553 conformance. -The current code is based on pre-RFC2553 specification. diff --git a/lib/libc/net/inet6_opt_init.3 b/lib/libc/net/inet6_opt_init.3 deleted file mode 100644 index e397099..0000000 --- a/lib/libc/net/inet6_opt_init.3 +++ /dev/null @@ -1,319 +0,0 @@ -.\" $KAME: inet6_opt_init.3,v 1.5 2002/10/17 14:13:47 jinmei Exp $ -.\" -.\" Copyright (C) 2000 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. -.\" -.\" $FreeBSD$ -.\" -.Dd February 5, 2000 -.Dt INET6_OPT_INIT 3 -.Os -.\" -.Sh NAME -.Nm inet6_opt_init , -.Nm inet6_opt_append , -.Nm inet6_opt_finish , -.Nm inet6_opt_set_val , -.Nm inet6_opt_next , -.Nm inet6_opt_find , -.Nm inet6_opt_get_val -.Nd IPv6 Hop-by-Hop and Destination Options manipulation -.\" -.Sh SYNOPSIS -.In netinet/in.h -.Ft "int" -.Fn inet6_opt_init "void *extbuf" "socklen_t extlen" -.Ft "int" -.Fn inet6_opt_append "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t len" "u_int8_t align" "void **databufp" -.Ft "int" -.Fn inet6_opt_finish "void *extbuf" "socklen_t extlen" "int offset" -.Ft "int" -.Fn inet6_opt_set_val "void *databuf" "int offset" "void *val" "socklen_t vallen" -.Ft "int" -.Fn inet6_opt_next "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t *typep" "socklen_t *lenp" "void **databufp" -.Ft "int" -.Fn inet6_opt_find "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t *lenp" "void **databufp" -.Ft "int" -.Fn inet6_opt_get_val "void *databuf" "socklen_t offset" "void *val" "socklen_t vallen" -.\" -.Sh DESCRIPTION -Building and parsing the Hop-by-Hop and Destination options is -complicated. -The advanced API therefore defines a set -of functions to help applications. -These functions assume the -formatting rules specified in Appendix B in RFC2460, i.e., that the -largest field is placed last in the option. -The function prototypes for -these functions are all in the -.In netinet/in.h -header. -.\" -.Ss inet6_opt_init -The -.Fn inet6_opt_init -function -returns the number of bytes needed for the empty -extension header, i.e., without any options. -If -.Va extbuf -is not -.Dv NULL -it also initializes the extension header to have the correct length -field. -In that case if the -.Fa extlen -value is not a positive -(i.e., non-zero) -multiple of 8 the function fails and returns \-1. -.\" -.Ss inet6_opt_append -The -.Fn inet6_opt_append -function -returns the updated total length taking into account -adding an option with length -.Fa len -and alignment -.Fa align . -The -.Fa offset -argument -should be the length returned by -.Fn inet6_opt_init -or a previous -.Fn inet6_opt_append . -If -.Fa extbuf -is not -.Dv NULL -then, in addition to returning the length, -the function inserts any needed pad option, initializes the option -(setting the type and length fields) -and returns a pointer to the location for the option content in -.Fa databufp . -.Pp -The -.Fa type -argument -is the 8-bit option type. -The -.Fa len -argument -is the length of the option data -(i.e., excluding the option type and option length fields). -.Pp -Once -.Fn inet6_opt_append -has been called, the application can use the -databuf directly, or use -.Fn inet6_opt_set_val -to specify the content of the option. -.Pp -The option type must have a value from 2 to 255, inclusive. -(0 and 1 are reserved for the Pad1 and PadN options, respectively.) -.Pp -The option data length must have a value between 0 and 255, -inclusive, and is the length of the option data that follows. -.Pp -The -.Fa align -parameter must have a value of 1, 2, 4, or 8. -The align value can not exceed the value of -.Fa len . -.\" -.Ss inet6_opt_finish -The -.Fn inet6_opt_finish -function -returns the updated total length -taking into account the final padding of the extension header to make -it a multiple of 8 bytes. -The -.Fa offset -argument -should be the length returned by -.Fn inet6_opt_init -or -.Fn inet6_opt_append . -If -.Fa extbuf -is not -.Dv NULL -the function also -initializes the option by inserting a Pad1 or PadN option of the -proper length. -.Pp -If the necessary pad does not fit in the extension header buffer the -function returns \-1. -.\" -.Ss inet6_opt_set_val -The -.Fn inet6_opt_set_val -function -inserts data items of various sizes in the data portion of the option. -The -.Fa databuf -argument -should be a pointer returned by -.Fn inet6_opt_append . -The -.Fa val -argument -should point to the data to be -inserted. -The -.Fa offset -argument -specifies where in the data portion of the option -the value should be inserted; the first byte after the option type -and length is accessed by specifying an offset of zero. -.Pp -The caller should ensure that each field is aligned on its natural -boundaries as described in Appendix B of RFC2460, but the function -must not rely on the caller's behavior. -Even when the alignment requirement is not satisfied, -the function should just copy the data as required. -.Pp -The function returns the offset for the next field -(i.e., -.Fa offset -+ -.Fa vallen ) -which can be used when composing option content with multiple fields. -.\" -.Ss inet6_opt_next -The -.Fn inet6_opt_next -function -parses received extension headers returning the next -option. -The -.Fa extbuf -and -.Fa extlen -arguments specify the extension header. -The -.Fa offset -argument -should either be zero (for the first option), or the length returned -by a previous call to -.Fn inet6_opt_next -or -.Fn inet6_opt_find . -It specifies the position where to continue scanning the extension -buffer. -The next option is returned by updating -.Fa typep , lenp , -and -.Fa databufp . -This function returns the updated -.Dq previous -length -computed by advancing past the option that was returned. -This returned -.Dq previous -length can then be passed to subsequent calls to -.Fn inet6_opt_next . -This function does not return any PAD1 or PADN options. -When there are no more options the return value is \-1. -.\" -.Ss inet6_opt_get_val -The -.Fn inet6_opt_get_val -function extracts data items of various sizes -in the data portion of the option. -The -.Fa databuf -argument -should be a pointer returned by -.Fn inet6_opt_next -or -.Fn inet6_opt_find . -The -.Fa val -argument -should point to the destination for the extracted data. -The -.Fa offset -argument -specifies from where in the data portion of the option the value should be -extracted; the first byte after the option type and length is -accessed by specifying an offset of zero. -.Pp -It is expected that each field is aligned on its natural boundaries -as described in Appendix B of RFC2460, but the function must not -rely on the alignment. -.Pp -The function returns the offset for the next field -(i.e., -.Fa offset -+ -.Fa vallen ) -which can be used when extracting option content with -multiple fields. -Robust receivers might want to verify alignment before calling -this function. -.\" -.Sh EXAMPLES -draft-ietf-ipngwg-rfc2292bis-08.txt -gives comprehensive examples in Section 23. -.Pp -KAME also provides examples in the advapitest directory of its kit. -.\" -.Sh DIAGNOSTICS -All the functions return -\-1 -on an error. -.\" -.Sh SEE ALSO -.Rs -.%A W. Stevens -.%A M. Thomas -.%A E. Nordmark -.%A T. Jinmei -.%T "Advanced Sockets API for IPv6" -.%N draft-ietf-ipngwg-rfc2292bis-08 -.%D October 2002 -.Re -.Rs -.%A S. Deering -.%A R. Hinden -.%T "Internet Protocol, Version 6 (IPv6) Specification" -.%N RFC2460 -.%D December 1998 -.Re -.Sh STANDARDS -The functions -are documented in -.Dq Advanced Sockets API for IPv6 -.Pq draft-ietf-ipngwg-rfc2292bis-08.txt . -.\" -.Sh HISTORY -The implementation first appeared in KAME advanced networking kit. -.Sh BUGS -The text was shamelessly copied from internet-drafts for RFC2292bis. diff --git a/lib/libc/net/inet6_option_space.3 b/lib/libc/net/inet6_option_space.3 deleted file mode 100644 index cf49fdf..0000000 --- a/lib/libc/net/inet6_option_space.3 +++ /dev/null @@ -1,485 +0,0 @@ -.\" 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. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. 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. -.\" -.\" $Id: inet6_option_space.3,v 1.4 2000/02/05 10:32:24 jinmei Exp $ -.\" $FreeBSD$ -.\" -.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 LIBRARY -.Lb libc -.Sh SYNOPSIS -.In sys/types.h -.In 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. -RFC2292 defines a set of functions to help the application. -The function prototypes for -these functions are all in the -.In netinet/in.h -header. -.\" -.Ss inet6_option_space -The -.Fn inet6_option_space -function -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 -(to make its size a multiple of 8 bytes). -The argument is the size of the structure defining the option, -which must include any pad bytes at the beginning -(the value -.Li y -in the alignment term -.Dq Li "xn + y" ) , -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 -(appendix B of [RFC-2460]). -.\" -.Ss inet6_option_init -The -.Fn inet6_option_init -function -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 -The -.Fa bp -argument -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 -The -.Fa cmsgp -argument -is a pointer to a pointer to a -.Li cmsghdr -structure. -The -.Fa *cmsgp -argument -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 -The -.Fa type -argument -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 -The -.Fa cmsg -argument -is a pointer to the -.Li cmsghdr -structure that must have been -initialized by -.Fn inet6_option_init . -.Pp -The -.Fa typep -argument -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 -(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. -.Li ( 0 -and -.Li 1 -are reserved for the -.Li Pad1 -and -.Li PadN -options, respectively.) -.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 -The -.Fa multx -argument -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 -The -.Fa plusy -argument -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 -The -.Fa cmsg -argument -is a pointer to the -.Li cmsghdr -structure that must have been -initialized by -.Fn inet6_option_init . -.Pp -The -.Fa datalen -argument -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 -The -.Fa multx -argument -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 -The -.Fa plusy -argument -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 -The -.Fa cmsg -argument -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 -The -.Fa tptrp -argument -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. -The -.Fa cmsg -argument -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 -The -.Fa tptrp -argument -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 -RFC2292 gives comprehensive examples in chapter 6. -.\" -.Sh DIAGNOSTICS -The -.Fn inet6_option_init -and -.Fn inet6_option_append -functions -return -.Li 0 -on success or -.Li -1 -on an error. -.Pp -The -.Fn inet6_option_alloc -function -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 RFC2292 -.%D February 1998 -.Re -.Rs -.%A S. Deering -.%A R. Hinden -.%T "Internet Protocol, Version 6 (IPv6) Specification" -.%N RFC2460 -.%D December 1998 -.Re -.\" -.Sh STANDARDS -The functions -are documented in -.Dq Advanced Sockets API for IPv6 -(RFC2292). -.\" -.Sh HISTORY -The implementation first appeared in KAME advanced networking kit. -.\" -.Sh BUGS -The text was shamelessly copied from RFC2292. diff --git a/lib/libc/net/inet6_rth_space.3 b/lib/libc/net/inet6_rth_space.3 deleted file mode 100644 index e10d8e5..0000000 --- a/lib/libc/net/inet6_rth_space.3 +++ /dev/null @@ -1,273 +0,0 @@ -.\" $KAME: kame/kame/kame/libinet6/inet6_rth_space.3,v 1.4 2002/10/17 14:13:48 jinmei Exp $ -.\" -.\" Copyright (C) 2000 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. -.\" -.\" $FreeBSD$ -.\" -.Dd February 5, 2000 -.Dt INET6_RTH_SPACE 3 -.Os -.\" -.Sh NAME -.Nm inet6_rth_space , -.Nm inet6_rth_init , -.Nm inet6_rth_add , -.Nm inet6_rth_reverse , -.Nm inet6_rth_segments , -.Nm inet6_rth_getaddr -.Nd IPv6 Routing Header Options manipulation -.\" -.Sh SYNOPSIS -.In netinet/in.h -.Ft socklen_t -.Fn inet6_rth_space "int" "int" -.Ft "void *" -.Fn inet6_rth_init "void *" "socklen_t" "int" "int" -.Ft int -.Fn inet6_rth_add "void *" "const struct in6_addr *" -.Ft int -.Fn inet6_rth_reverse "const void *" "void *" -.Ft int -.Fn inet6_rth_segments "const void *" -.Ft "struct in6_addr *" -.Fn inet6_rth_getaddr "const void *" "int" -.\" -.Sh DESCRIPTION -The IPv6 advanced API defines six -functions that the application calls to build and examine a Routing -header, and the ability to use sticky options or ancillary data to -communicate this information between the application and the kernel -using the IPV6_RTHDR option. -.Pp -Three functions build a Routing header: -.Bl -hang -.It Fn inet6_rth_space -returns #bytes required for Routing header -.It Fn inet6_rth_init -initializes buffer data for Routing header -.It Fn inet6_rth_add -adds one IPv6 address to the Routing header -.El -.Pp -Three functions deal with a returned Routing header: -.Bl -hang -.It Fn inet6_rth_reverse -reverses a Routing header -.It Fn inet6_rth_segments -returns #segments in a Routing header -.It Fn inet6_rth_getaddr -fetches one address from a Routing header -.El -.Pp -The function prototypes for these functions are defined as a result -of including the -.In netinet/in.h -header. -.\" -.Ss inet6_rth_space -The -.Fn inet6_rth_space -function -returns the number of bytes required to hold a Routing -header of the specified type containing the specified number of -segments (addresses). -For an IPv6 Type 0 Routing header, the number -of -segments -must be between 0 and 127, inclusive. -The return value is just the space for the Routing header. -When the application uses -ancillary data it must pass the returned length to -.Fn CMSG_LEN -to determine how much memory is needed for the ancillary data object -(including the -.Vt cmsghdr -structure). -.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 msg_control buffer. -.Ss inet6_rth_init -The -.Fn inet6_rth_init -function -initializes the buffer pointed to by -.Fa bp -to contain a -Routing header of the specified type and sets -.Va ip6r_len -based on the -.Fa segments -parameter. -The -.Fa bp_len -argument -is only used to verify that the buffer is -large enough. -The -.Va ip6r_segleft -field is set to zero; -.Fn inet6_rth_add -will increment it. -.Pp -When the application uses ancillary data the application must -initialize any -.Vt cmsghdr -fields. -.Pp -The caller must allocate the buffer and its size can be determined by -calling -.Fn inet6_rth_space . -.Pp -Upon success the return value is the pointer to the buffer -.Fa bp , -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_rth_add -The -.Fn inet6_rth_add -function -adds the IPv6 address pointed to by -.Fa addr -to the end of the Routing header being constructed. -.Pp -If successful, the -.Va segleft -member of the Routing Header 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_rth_reverse -The -.Fn inet6_rth_reverse -function -takes a Routing header extension header -(pointed to by the first argument -.Fa in ) -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 -(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_rth_segments -The -.Fn inet6_rth_segments -function -returns the number of segments -(addresses) -contained in the Routing header described by -.Fa bp . -On success the return value is -zero or greater. -The return value of the function is \-1 upon an error. -.\" -.Ss inet6_rth_getaddr -The -.Fn inet6_rth_getaddr -function -returns a pointer to the IPv6 address specified by -.Fa index -(which must have a value between 0 and one less than the value -returned by -.Fn inet6_rth_segments ) -in the Routing header described by -.Fa bp . -An application should first call -.Fn inet6_rth_segments -to obtain the number of segments in the Routing header. -.Pp -Upon an error the return value of the function is -.Dv NULL . -.\" -.Sh EXAMPLES -draft-ietf-ipngwg-rfc2292bis-08.txt -gives comprehensive examples in Section 22. -.Pp -KAME also provides examples in the advapitest directory of its kit. -.\" -.Sh DIAGNOSTICS -The -.Fn inet6_rth_space -and -.Fn inet6_rth_getaddr -functions -return 0 on errors. -.Pp -The -.Fn inet6_rthdr_init -function -returns -.Dv NULL -on error. -The -.Fn inet6_rth_add -and -.Fn inet6_rth_reverse -functions -return 0 on success, or \-1 upon an error. -.\" -.Sh SEE ALSO -.Rs -.%A W. Stevens -.%A M. Thomas -.%A E. Nordmark -.%A E. Jinmei -.%T "Advanced Sockets API for IPv6" -.%N draft-ietf-ipngwg-rfc2292bis-08 -.%D October 2002 -.Re -.Rs -.%A S. Deering -.%A R. Hinden -.%T "Internet Protocol, Version 6 (IPv6) Specification" -.%N RFC2460 -.%D December 1998 -.Re -.Sh STANDARDS -The functions -are documented in -.Dq Advanced Sockets API for IPv6 -.Pq draft-ietf-ipngwg-rfc2292bis-08.txt . -.\" -.Sh HISTORY -The implementation first appeared in KAME advanced networking kit. -.Sh BUGS -The text was shamelessly copied from internet-drafts for RFC2292bis. diff --git a/lib/libc/net/inet6_rthdr_space.3 b/lib/libc/net/inet6_rthdr_space.3 deleted file mode 100644 index 4de2359..0000000 --- a/lib/libc/net/inet6_rthdr_space.3 +++ /dev/null @@ -1,335 +0,0 @@ -.\" 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. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. 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. -.\" -.\" $Id: inet6_rthdr_space.3,v 1.5 2000/02/05 13:19:07 jinmei Exp $ -.\" $FreeBSD$ -.\" -.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 LIBRARY -.Lb libc -.Sh SYNOPSIS -.In sys/types.h -.In 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 -RFC2292 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 -.In 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 -(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 is not yet implemented. -When implemented, this should behave as follows. -.Pp -This function takes a Routing header that was received as ancillary -data -(pointed to by the first argument, -.Fa in ) -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 -(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 -(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 RFC2460. -.\" -.Sh EXAMPLES -RFC2292 gives comprehensive examples in chapter 8. -.\" -.Sh DIAGNOSTICS -The -.Fn inet6_rthdr_space -function -returns 0 on errors. -.Pp -The -.Fn inet6_rthdr_add , -.Fn inet6_rthdr_lasthop -and -.Fn inet6_rthdr_reverse -functions -return 0 on success, and returns -1 on error. -.Pp -The -.Fn inet6_rthdr_init -and -.Fn inet6_rthdr_getaddr -functions -return -.Dv NULL -on error. -.Pp -The -.Fn inet6_rthdr_segments -and -.Fn inet6_rthdr_getflags -functions -return -1 on error. -.\" -.Sh SEE ALSO -.Rs -.%A W. Stevens -.%A M. Thomas -.%T "Advanced Sockets API for IPv6" -.%N RFC2292 -.%D February 1998 -.Re -.Rs -.%A S. Deering -.%A R. Hinden -.%T "Internet Protocol, Version 6 (IPv6) Specification" -.%N RFC2460 -.%D December 1998 -.Re -.\" -.Sh STANDARDS -The functions -are documented in -.Dq Advanced Sockets API for IPv6 -(RFC2292). -.\" -.Sh HISTORY -The implementation first appeared in KAME advanced networking kit. -.\" -.Sh BUGS -The text was shamelessly copied from RFC2292. -.Pp -The -.Fn inet6_rthdr_reverse -function -is not implemented yet. diff --git a/share/man/man4/icmp6.4 b/share/man/man4/icmp6.4 deleted file mode 100644 index ccaf059..0000000 --- a/share/man/man4/icmp6.4 +++ /dev/null @@ -1,267 +0,0 @@ -.\" 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. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. 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. -.\" -.\" KAME $Id: icmp6.4,v 1.1 1999/12/17 09:47:01 itojun Exp $ -.\" $FreeBSD$ -.\" -.Dd March 13, 2000 -.Dt ICMP6 4 -.Os -.\" -.Sh NAME -.Nm icmp6 -.Nd Internet Control Message Protocol for IPv6 -.\" -.Sh SYNOPSIS -.In sys/types.h -.In sys/socket.h -.In netinet/in.h -.In 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 -(based on the destination address). -.Tn ICMPv6 -pseudo header checksum field -.Pq Li icmp6_cksum -will be filled automatically by the kernel. -Incoming packets are received without the -.Tn IPv6 -header nor IPv6 extension headers. -Notice that this behavior is opposite from -.Tn IPv4 -raw sockets and. -.Tn ICMPv4 -sockets. -.Pp -.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 -.In 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? -.Bl -item -offset indent -.It -.Ft void -.Fn ICMP6_FILTER_SETPASSALL "struct icmp6_filter *filterp" -.It -.Ft void -.Fn ICMP6_FILTER_SETBLOCKALL "struct icmp6_filter *filterp" -.It -.Ft void -.Fn ICMP6_FILTER_SETPASS "int type" "struct icmp6_filter *filterp" -.It -.Ft void -.Fn ICMP6_FILTER_SETBLOCK "int type" "struct icmp6_filter *filterp" -.It -.Ft int -.Fn ICMP6_FILTER_WILLPASS "int type" "const struct icmp6_filter *filterp" -.It -.Ft int -.Fn ICMP6_FILTER_WILLBLOCK "int type" "const struct icmp6_filter *filterp" -.El -.Pp -The first argument to the last four macros -(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 , -let us 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 , -let us specify that -messages of a given -.Tn ICMPv6 -type should be passed to the application -or not passed to the application -(blocked). -.Pp -The final two macros, -.Dv WILLPASS -and -.Dv WILLBLOCK , -return true or false -depending 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 RFC2292. -.\" -.Sh ERRORS -A socket operation may fail with one of the following errors returned: -.Bl -tag -width Er -.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 intro 4 , -.Xr ip6 4 -.Rs -.%A W. Stevens -.%A M. Thomas -.%R RFC -.%N 2292 -.%D February 1998 -.%T "Advanced Sockets API for IPv6" -.Re -.Rs -.%A A. Conta -.%A S. Deering -.%R RFC -.%N 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 -(which is descendant of WIDE hydrangea IPv6 stack kit). -.Pp -Part of the document was shamelessly copied from RFC2292. diff --git a/share/man/man4/ip6.4 b/share/man/man4/ip6.4 deleted file mode 100644 index a3e38de..0000000 --- a/share/man/man4/ip6.4 +++ /dev/null @@ -1,710 +0,0 @@ -.\" $KAME: ip6.4,v 1.14 2001/02/26 09:31: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. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. 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. -.\" -.\" $FreeBSD$ -.\" -.Dd March 13, 2000 -.Dt IP6 4 -.Os -.\" -.Sh NAME -.Nm ip6 -.Nd Internet Protocol version 6 (IPv6) -.\" -.Sh SYNOPSIS -.In sys/types.h -.In sys/socket.h -.In 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 / Ns Xr getsockopt 2 -options. -They are separated into the basic IPv6 sockets API -(defined in RFC2553), -and the advanced API -(defined in RFC2292). -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 of socket options, certain 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 symbol name suggests, the option controls 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 -.Er 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 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; - u_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 -.Pp -.Dv IPV6_V6ONLY -controls behavior of -.Dv AF_INET6 -wildcard listening socket. -The following example sets the option to 1: -.Bd -literal -offset indent -int on = 1; -setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY, &on, sizeof(on)); -.Ed -.Pp -If set to 1, -.Dv AF_INET6 -wildcard listening socket will accept IPv6 traffic only. -If set to 0, it will accept IPv4 traffic as well, -as if it was from IPv4 mapped address like -.Li ::ffff:10.1.1.1 . -.\" RFC2553 defines the behavior when the variable is set to 0. -Note that if you set it this to 0, -IPv4 access control gets much more complicated. -For example, even if you have no listening -.Dv AF_INET -listening socket on port -.Li X , -you will end up accepting IPv4 traffic by -.Dv AF_INET6 -listening socket on the same port. -The default value for this flag is copied at socket instantiation time, -from -.Li net.inet6.ip6.v6only -.Xr sysctl 3 -variable. -The option affects -.Tn TCP -and -.Tn UDP -sockets only. -.\" -.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 / 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 -equals to -.Dv IPPROTO_IPV6 , -and -.Li cmsg_type -equals to -.Dv IPV6_PKTINFO . -.Pp -If -.Dv IPV6_HOPLIMIT -is enabled, hoplimit value on the packet will be made available to the -userland program. -Ancillary data stream will contain an integer data item with -.Li cmsg_level -equals to -.Dv IPPROTO_IPV6 , -and -.Li cmsg_type -equals to -.Dv IPV6_HOPLIMIT . -.Pp -.Xr inet6_option_space 3 -and friends will help you parse ancillary data items for -.Dv IPV6_HOPOPTS -and -.Dv IPV6_DSTOPTS . -Similarly, -.Xr inet6_rthdr_space 3 -and friends will help you 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 item will appear no more than once. -.Pp -For outgoing direction, -you can pass ancillary data items with normal payload data, 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, ancillary data format is the same as inbound case. -Additionally, you can specify -.Dv IPV6_NEXTHOP -data object. -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 (e.g., 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 unable to use -.Xr sendmsg 2 -or -.Xr recvmsg 2 , -.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 -.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 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 -.Tn IPv6 -header nor 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 for -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 RFC2460. -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 ERRORS -A socket operation may fail with one of the following errors returned: -.Bl -tag -width Er -.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 , -.Xr intro 4 -.Rs -.%A W. Stevens -.%A M. Thomas -.%R RFC -.%N 2292 -.%D February 1998 -.%T "Advanced Sockets API for IPv6" -.Re -.Rs -.%A S. Deering -.%A R. Hinden -.%R RFC -.%N 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 -.%N 2553 -.%D March 1999 -.%T "Basic Socket Interface Extensions for IPv6" -.Re -.\" -.Sh STANDARDS -Most of the socket options are defined in -RFC2292 and/or RFC2553. -.Pp -.Dv IPV6_V6ONLY -socket option is defined in draft-ietf-ipngwg-rfc2553bis-03. -.Dv IPV6_PORTRANGE -socket option -and -conflict resolution rule -are not defined in the RFCs and should be considered implementation dependent. -.\" -.Sh HISTORY -The implementation is based on KAME stack -(which is descendant of WIDE hydrangea IPv6 stack kit). -.Pp -Part of the document was shamelessly copied from RFC2553 and RFC2292. -.\" -.Sh BUGS -The -.Dv IPV6_NEXTHOP -object/option is not fully implemented as of writing this. |
