diff options
-rw-r--r-- | lib/libc/net/gai_strerror.3 | 94 | ||||
-rw-r--r-- | lib/libc/net/getaddrinfo.3 | 435 | ||||
-rw-r--r-- | lib/libc/net/getnameinfo.3 | 271 | ||||
-rw-r--r-- | lib/libc/net/inet6_opt_init.3 | 337 | ||||
-rw-r--r-- | lib/libc/net/inet6_option_space.3 | 434 | ||||
-rw-r--r-- | lib/libc/net/inet6_rth_space.3 | 223 | ||||
-rw-r--r-- | lib/libc/net/inet6_rthdr_space.3 | 305 | ||||
-rw-r--r-- | share/man/man4/icmp6.4 | 255 | ||||
-rw-r--r-- | share/man/man4/ip6.4 | 686 |
9 files changed, 3040 insertions, 0 deletions
diff --git a/lib/libc/net/gai_strerror.3 b/lib/libc/net/gai_strerror.3 new file mode 100644 index 0000000..97e3d6d --- /dev/null +++ b/lib/libc/net/gai_strerror.3 @@ -0,0 +1,94 @@ +.\" $KAME: gai_strerror.3,v 1.1 2005/01/05 03:04:47 itojun Exp $ +.\" $OpenBSD: gai_strerror.3,v 1.4 2004/12/20 23:04:53 millert Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2000, 2001 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd December 20, 2004 +.Dt GAI_STRERROR 3 +.Os +.Sh NAME +.Nm gai_strerror +.Nd get error message string from EAI_xxx error code +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/socket.h> +.Fd #include <netdb.h> +.Ft "const char *" +.Fn gai_strerror "int ecode" +.Sh DESCRIPTION +The +.Fn gai_strerror +function returns an error message string corresponding to the error code +returned by +.Xr getaddrinfo 3 +or +.Xr getnameinfo 3 . +.Pp +The following error codes and their meaning are defined in +.Aq Pa netdb.h : +.Pp +.Bl -tag -width "EAI_ADDRFAMILYXX" -offset indent -compact +.It Dv EAI_ADDRFAMILY +address family for +.Fa hostname +not supported +.It Dv EAI_AGAIN +temporary failure in name resolution +.It Dv EAI_BADFLAGS +invalid value for +.Fa ai_flags +.It Dv EAI_BADHINTS +invalid value for +.Fa hints +.It Dv EAI_FAIL +non-recoverable failure in name resolution +.It Dv EAI_FAMILY +.Fa ai_family +not supported. +.It Dv EAI_MEMORY +memory allocation failure +.It Dv EAI_NODATA +no address associated with +.Fa hostname +.It Dv EAI_NONAME +.Fa hostname +or +.Fa servname +not provided, or not known +.It Dv EAI_PROTOCOL +resolved protocol is unknown +.It Dv EAI_SERVICE +.Fa servname +not supported for +.Fa ai_socktype +.It Dv EAI_SOCKTYPE +.Fa ai_socktype +not supported +.It Dv EAI_SYSTEM +system error returned in +.Va errno +.El +.Sh RETURN VALUES +.Fn gai_strerror +returns a pointer to the error message string corresponding to +.Fa ecode . +If +.Fa ecode +is out of range, an implementation-specific error message string is returned. +.Sh SEE ALSO +.Xr getaddrinfo 3 , +.Xr getnameinfo 3 diff --git a/lib/libc/net/getaddrinfo.3 b/lib/libc/net/getaddrinfo.3 new file mode 100644 index 0000000..bdaebe3 --- /dev/null +++ b/lib/libc/net/getaddrinfo.3 @@ -0,0 +1,435 @@ +.\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $ +.\" $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2000, 2001 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd December 20, 2004 +.Dt GETADDRINFO 3 +.Os +.Sh NAME +.Nm getaddrinfo , +.Nm freeaddrinfo +.Nd socket address structure to host and service name +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/socket.h> +.Fd #include <netdb.h> +.Ft int +.Fn getaddrinfo "const char *hostname" "const char *servname" \ + "const struct addrinfo *hints" "struct addrinfo **res" +.Ft void +.Fn freeaddrinfo "struct addrinfo *ai" +.Sh DESCRIPTION +The +.Fn getaddrinfo +function is used to get a list of +.Tn IP +addresses and port numbers for host +.Fa hostname +and service +.Fa servname . +It is a replacement for and provides more flexibility than the +.Xr gethostbyname 3 +and +.Xr getservbyname 3 +functions. +.Pp +The +.Fa hostname +and +.Fa servname +arguments are either pointers to NUL-terminated strings or the null pointer. +An acceptable value for +.Fa hostname +is either a valid host name or a numeric host address string consisting +of a dotted decimal IPv4 address or an IPv6 address. +The +.Fa servname +is either a decimal port number or a service name listed in +.Xr services 5 . +At least one of +.Fa hostname +and +.Fa servname +must be non-null. +.Pp +.Fa hints +is an optional pointer to a +.Li struct addrinfo , +as defined by +.Aq Pa netdb.h : +.Bd -literal +struct addrinfo { + int ai_flags; /* input flags */ + int ai_family; /* protocol family for socket */ + int ai_socktype; /* socket type */ + int ai_protocol; /* protocol for socket */ + socklen_t ai_addrlen; /* length of socket-address */ + struct sockaddr *ai_addr; /* socket-address for socket */ + char *ai_canonname; /* canonical name for service location */ + struct addrinfo *ai_next; /* pointer to next in list */ +}; +.Ed +.Pp +This structure can be used to provide hints concerning the type of socket +that the caller supports or wishes to use. +The caller can supply the following structure elements in +.Fa hints : +.Bl -tag -width "ai_socktypeXX" +.It Fa ai_family +The protocol family that should be used. +When +.Fa ai_family +is set to +.Dv PF_UNSPEC , +it means the caller will accept any protocol family supported by the +operating system. +.It Fa ai_socktype +Denotes the type of socket that is wanted: +.Dv SOCK_STREAM , +.Dv SOCK_DGRAM , +or +.Dv SOCK_RAW . +When +.Fa ai_socktype +is zero the caller will accept any socket type. +.It Fa ai_protocol +Indicates which transport protocol is desired, +.Dv IPPROTO_UDP +or +.Dv IPPROTO_TCP . +If +.Fa ai_protocol +is zero the caller will accept any protocol. +.It Fa ai_flags +.Fa ai_flags +is formed by +.Tn OR Ns 'ing +the following values: +.Bl -tag -width "AI_CANONNAMEXX" +.It Dv AI_CANONNAME +If the +.Dv AI_CANONNAME +bit is set, a successful call to +.Fn getaddrinfo +will return a NUL-terminated string containing the canonical name +of the specified hostname in the +.Fa ai_canonname +element of the first +.Li addrinfo +structure returned. +.It Dv AI_NUMERICHOST +If the +.Dv AI_NUMERICHOST +bit is set, it indicates that +.Fa hostname +should be treated as a numeric string defining an IPv4 or IPv6 address +and no name resolution should be attempted. +.It Dv AI_PASSIVE +If the +.Dv AI_PASSIVE +bit is set it indicates that the returned socket address structure +is intended for use in a call to +.Xr bind 2 . +In this case, if the +.Fa hostname +argument is the null pointer, then the IP address portion of the +socket address structure will be set to +.Dv INADDR_ANY +for an IPv4 address or +.Dv IN6ADDR_ANY_INIT +for an IPv6 address. +.Pp +If the +.Dv AI_PASSIVE +bit is not set, the returned socket address structure will be ready +for use in a call to +.Xr connect 2 +for a connection-oriented protocol or +.Xr connect 2 , +.Xr sendto 2 , +or +.Xr sendmsg 2 +if a connectionless protocol was chosen. +The +.Tn IP +address portion of the socket address structure will be set to the +loopback address if +.Fa hostname +is the null pointer and +.Dv AI_PASSIVE +is not set. +.El +.El +.Pp +All other elements of the +.Li addrinfo +structure passed via +.Fa hints +must be zero or the null pointer. +.Pp +If +.Fa hints +is the null pointer, +.Fn getaddrinfo +behaves as if the caller provided a +.Li struct addrinfo +with +.Fa ai_family +set to +.Dv PF_UNSPEC +and all other elements set to zero or +.Dv NULL . +.Pp +After a successful call to +.Fn getaddrinfo , +.Fa *res +is a pointer to a linked list of one or more +.Li addrinfo +structures. +The list can be traversed by following the +.Fa ai_next +pointer in each +.Li addrinfo +structure until a null pointer is encountered. +The three members +.Fa ai_family, +.Fa ai_socktype, +and +.Fa ai_protocol +in each returned +.Li addrinfo +structure are suitable for a call to +.Xr socket 2 . +For each +.Li addrinfo +structure in the list, the +.Fa ai_addr +member points to a filled-in socket address structure of length +.Fa ai_addrlen . +.Pp +This implementation of +.Fn getaddrinfo +allows numeric IPv6 address notation with scope identifier, +as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. +By appending the percent character and scope identifier to addresses, +one can fill the +.Li sin6_scope_id +field for addresses. +This would make management of scoped addresses easier +and allows cut-and-paste input of scoped addresses. +.Pp +At this moment the code supports only link-local addresses with the format. +The scope identifier is hardcoded to the name of the hardware interface +associated +with the link +.Po +such as +.Li ne0 +.Pc . +An example is +.Dq Li fe80::1%ne0 , +which means +.Do +.Li fe80::1 +on the link associated with the +.Li ne0 +interface +.Dc . +.Pp +The current implementation assumes a one-to-one relationship between +the interface and link, which is not necessarily true from the specification. +.Pp +All of the information returned by +.Fn getaddrinfo +is dynamically allocated: the +.Li addrinfo +structures themselves as well as the socket address structures and +the canonical host name strings included in the +.Li addrinfo +structures. +.Pp +Memory allocated for the dynamically allocated structures created by +a successful call to +.Fn getaddrinfo +is released by the +.Fn freeaddrinfo +function. +The +.Fa ai +pointer should be a +.Li addrinfo +structure created by a call to +.Fn getaddrinfo . +.Sh RETURN VALUES +.Fn getaddrinfo +returns zero on success or one of the error codes listed in +.Xr gai_strerror 3 +if an error occurs. +.Sh EXAMPLES +The following code tries to connect to +.Dq Li www.kame.net +service +.Dq Li http +via a stream socket. +It loops through all the addresses available, regardless of 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 a 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; +for (res = res0; res; res = res->ai_next) { + s = socket(res->ai_family, res->ai_socktype, + res->ai_protocol); + if (s < 0) { + cause = "socket"; + continue; + } + + if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { + cause = "connect"; + close(s); + s = -1; + continue; + } + + break; /* okay we got one */ +} +if (s < 0) { + err(1, "%s", cause); + /*NOTREACHED*/ +} +freeaddrinfo(res0); +.Ed +.Pp +The following example tries to open a wildcard listening socket onto service +.Dq Li http , +for all the address families available. +.Bd -literal -offset indent +struct addrinfo hints, *res, *res0; +int error; +int s[MAXSOCK]; +int nsock; +const char *cause = NULL; + +memset(&hints, 0, sizeof(hints)); +hints.ai_family = PF_UNSPEC; +hints.ai_socktype = SOCK_STREAM; +hints.ai_flags = AI_PASSIVE; +error = getaddrinfo(NULL, "http", &hints, &res0); +if (error) { + errx(1, "%s", gai_strerror(error)); + /*NOTREACHED*/ +} +nsock = 0; +for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { + s[nsock] = socket(res->ai_family, res->ai_socktype, + res->ai_protocol); + if (s[nsock] < 0) { + cause = "socket"; + continue; + } + + if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { + cause = "bind"; + close(s[nsock]); + continue; + } + (void) listen(s[nsock], 5); + + nsock++; +} +if (nsock == 0) { + err(1, "%s", cause); + /*NOTREACHED*/ +} +freeaddrinfo(res0); +.Ed +.Sh SEE ALSO +.Xr bind 2 , +.Xr connect 2 , +.Xr send 2 , +.Xr socket 2 , +.Xr gai_strerror 3 , +.Xr gethostbyname 3 , +.Xr getnameinfo 3 , +.Xr getservbyname 3 , +.Xr resolver 3 , +.Xr hosts 5 , +.Xr resolv.conf 5 , +.Xr services 5 , +.Xr hostname 7 , +.Xr named 8 +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A J. McCann +.%A W. Stevens +.%T Basic Socket Interface Extensions for IPv6 +.%R RFC 3493 +.%D February 2003 +.Re +.Rs +.%A S. Deering +.%A B. Haberman +.%A T. Jinmei +.%A E. Nordmark +.%A B. Zill +.%T "IPv6 Scoped Address Architecture" +.%R internet draft +.%N draft-ietf-ipv6-scoping-arch-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 by the +.St -p1003.1g-2000 +draft specification and documented in +.Dv "RFC 3493" , +.Dq Basic Socket Interface Extensions for IPv6 . +.Sh BUGS +The implementation of +.Fn getaddrinfo +is not thread-safe. diff --git a/lib/libc/net/getnameinfo.3 b/lib/libc/net/getnameinfo.3 new file mode 100644 index 0000000..4cb6eb2 --- /dev/null +++ b/lib/libc/net/getnameinfo.3 @@ -0,0 +1,271 @@ +.\" $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $ +.\" $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2000, 2001 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd December 20, 2004 +.Dt GETNAMEINFO 3 +.Os +.Sh NAME +.Nm getnameinfo +.Nd socket address structure to hostname and service name +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/socket.h> +.Fd #include <netdb.h> +.Ft int +.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" "char *host" \ + "size_t hostlen" "char *serv" "size_t servlen" "int flags" +.Sh DESCRIPTION +The +.Fn getnameinfo +function is used to convert a +.Li sockaddr +structure to a pair of host name and service strings. +It is a replacement for and provides more flexibility than the +.Xr gethostbyaddr 3 +and +.Xr getservbyport 3 +functions and is the converse of the +.Xr getaddrinfo 3 +function. +.Pp +The +.Li sockaddr +structure +.Fa sa +should point to either a +.Li sockaddr_in +or +.Li sockaddr_in6 +structure (for IPv4 or IPv6 respectively) that is +.Fa salen +bytes long. +.Pp +The host and service names associated with +.Fa sa +are stored in +.Fa host +and +.Fa serv +which have length parameters +.Fa hostlen +and +.Fa servlen . +The maximum value for +.Fa hostlen +is +.Dv NI_MAXHOST +and +the maximum value for +.Fa servlen +is +.Dv NI_MAXSERV , +as defined by +.Aq Pa netdb.h . +If a length parameter is zero, no string will be stored. +Otherwise, enough space must be provided to store the +host name or service string plus a byte for the NUL terminator. +.Pp +The +.Fa flags +argument is formed by +.Tn OR Ns 'ing +the following values: +.Bl -tag -width "NI_NUMERICHOSTXX" +.It Dv NI_NOFQDN +A fully qualified domain name is not required for local hosts. +The local part of the fully qualified domain name is returned instead. +.It Dv NI_NUMERICHOST +Return the address in numeric form, as if calling +.Xr inet_ntop 3 , +instead of a host name. +.It Dv NI_NAMEREQD +A name is required. +If the host name cannot be found in DNS and this flag is set, +a non-zero error code is returned. +If the host name is not found and the flag is not set, the +address is returned in numeric form. +.It NI_NUMERICSERV +The service name is returned as a digit string representing the port number. +.It NI_DGRAM +Specifies that the service being looked up is a datagram +service, and causes +.Xr getservbyport 3 +to be called with a second argument of +.Dq udp +instead of its default of +.Dq tcp . +This is required for the few ports (512\-514) that have different services +for +.Tn UDP +and +.Tn TCP . +.El +.Pp +This implementation allows numeric IPv6 address notation with scope identifier, +as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. +IPv6 link-local address will appear as a string like +.Dq Li fe80::1%ne0 . +Refer to +.Xr getaddrinfo 3 +for more information. +.Sh RETURN VALUES +.Fn getnameinfo +returns zero on success or one of the error codes listed in +.Xr gai_strerror 3 +if an error occurs. +.Sh EXAMPLES +The following code tries to get a numeric host name, and service name, +for a given socket address. +Observe that there is no hardcoded reference to a particular address family. +.Bd -literal -offset indent +struct sockaddr *sa; /* input */ +char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; + +if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, + sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { + errx(1, "could not get numeric hostname"); + /*NOTREACHED*/ +} +printf("host=%s, serv=%s\en", hbuf, sbuf); +.Ed +.Pp +The following version checks if the socket address has a reverse address mapping: +.Bd -literal -offset indent +struct sockaddr *sa; /* input */ +char hbuf[NI_MAXHOST]; + +if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, + NI_NAMEREQD)) { + errx(1, "could not resolve hostname"); + /*NOTREACHED*/ +} +printf("host=%s\en", hbuf); +.Ed +.Sh SEE ALSO +.Xr gai_strerror 3 , +.Xr getaddrinfo 3 , +.Xr gethostbyaddr 3 , +.Xr getservbyport 3 , +.Xr inet_ntop 3 , +.Xr resolver 3 , +.Xr hosts 5 , +.Xr resolv.conf 5 , +.Xr services 5 , +.Xr hostname 7 , +.Xr named 8 +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A W. Stevens +.%T Basic Socket Interface Extensions for IPv6 +.%R RFC 2553 +.%D March 1999 +.Re +.Rs +.%A S. Deering +.%A B. Haberman +.%A T. Jinmei +.%A E. Nordmark +.%A B. Zill +.%T "IPv6 Scoped Address Architecture" +.%R internet draft +.%N draft-ietf-ipv6-scoping-arch-02.txt +.%O work in progress material +.Re +.Rs +.%A Craig Metz +.%T Protocol Independence Using the Sockets API +.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" +.%D June 2000 +.Re +.Sh STANDARDS +The +.Fn getnameinfo +function is defined by the +.St -p1003.1g-2000 +draft specification and documented in +.Tn "RFC 2553" , +.Dq Basic Socket Interface Extensions for IPv6 . +.Sh CAVEATS +.Fn getnameinfo +can return both numeric and FQDN forms of the address specified in +.Fa sa . +There is no return value that indicates whether the string returned in +.Fa host +is a result of binary to numeric-text translation (like +.Xr inet_ntop 3 ) , +or is the result of a DNS reverse lookup. +Because of this, malicious parties could set up a PTR record as follows: +.Bd -literal -offset indent +1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 +.Ed +.Pp +and trick the caller of +.Fn getnameinfo +into believing that +.Fa sa +is +.Li 10.1.1.1 +when it is actually +.Li 127.0.0.1 . +.Pp +To prevent such attacks, the use of +.Dv NI_NAMEREQD +is recommended when the result of +.Fn getnameinfo +is used +for access control purposes: +.Bd -literal -offset indent +struct sockaddr *sa; +socklen_t salen; +char addr[NI_MAXHOST]; +struct addrinfo hints, *res; +int error; + +error = getnameinfo(sa, salen, addr, sizeof(addr), + NULL, 0, NI_NAMEREQD); +if (error == 0) { + memset(&hints, 0, sizeof(hints)); + hints.ai_socktype = SOCK_DGRAM; /*dummy*/ + hints.ai_flags = AI_NUMERICHOST; + if (getaddrinfo(addr, "0", &hints, &res) == 0) { + /* malicious PTR record */ + freeaddrinfo(res); + printf("bogus PTR record\en"); + return -1; + } + /* addr is FQDN as a result of PTR lookup */ +} else { + /* addr is numeric string */ + error = getnameinfo(sa, salen, addr, sizeof(addr), + NULL, 0, NI_NUMERICHOST); +} +.Ed +.Sh BUGS +The implementation of +.Fn getnameinfo +is not thread-safe. +.\".Pp +.\".Ox +.\"intentionally uses a different +.\".Dv NI_MAXHOST +.\"value from what +.\".Tn "RFC 2553" +.\"suggests, to avoid buffer length handling mistakes. diff --git a/lib/libc/net/inet6_opt_init.3 b/lib/libc/net/inet6_opt_init.3 new file mode 100644 index 0000000..b668792 --- /dev/null +++ b/lib/libc/net/inet6_opt_init.3 @@ -0,0 +1,337 @@ +.\" $KAME: inet6_opt_init.3,v 1.7 2004/12/27 05:08:23 itojun Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (C) 2004 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. +.\" +.Dd December 23, 2004 +.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 sockets API defines a set of functions to +help applications create and manipulate Hop-by-Hope and Destination +options. +.\"This man page describes the functions specified in +.\"IETF Draft RFC3542 while the +.\".Xr inet6_options_space 3 +.\"man page documents the functions defined in RFC 2292. +.\"It is expected +.\"that this set of functions will supersede those in RFC 2292 but for +.\"the time being both APIs are retained. +These functions use 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 contained in the +.In netinet/in.h +header file. +.\" +.Ss inet6_opt_init +The +.Fn inet6_opt_init +function +returns the number of bytes needed for an empty +extension header, one without any options. +If the +.Va extbuf +argument points to a valid section of memory +then the +.Fn inet6_opt_init +function also initializes the extension header's length field. +When attempting to initialize an extension buffer passed in the +.Va extbuf argument +.Fa extlen +must be a positive multiple of 8 or else the function fails and +returns \-1 to the caller. +.\" +.Ss inet6_opt_append +The +.Fn inet6_opt_append +function can perform to different jobs. +When a valid +.Fa extbuf +argument is supplied it appends an option to the extension buffer and +returns the updated total length as well as a pointer to the newly +created option in +.Fa databufp . +If the value +of +.Fa extbuf +is +.Dv NULL +then the +.Fn inet6_opt_append function only reports what the total length would +be if the option were actually appended. +The +.Fa len +and +.Fa align +arguments specify the length of the option and the required data +alignment which must be used when appending the option. +The +.Fa offset +argument should be the length returned by the +.Fn inet6_opt_init +function or a previous call to +.Fn inet6_opt_append . +.Pp +The +.Fa type +argument is the 8-bit option type. +.Pp +After +.Fn inet6_opt_append +has been called, the application can use the buffer pointed to by +.Fa databufp +directly, or use +.Fn inet6_opt_set_val +to specify the data to be contained in the option. +.Pp +Option types of +.Li 0 +and +.Li 1 +are reserved for the +.Li Pad1 +and +.Li PadN +options. +All other values from 2 through 255 may be used by applications. +.Pp +The length of the option data is contained in an 8-bit value and so +may contain any value from 0 through 255. +.Pp +The +.Fa align +parameter must have a value of 1, 2, 4, or 8 and cannot exceed the +value of +.Fa len . +The alignment values represent no alignment, 16 bit, 32 bit and 64 bit +alignments respectively. +.\" +.Ss inet6_opt_finish +The +.Fn inet6_opt_finish +calculates the final padding necessary to make the extension header a +multiple of 8 bytes, as required by the IPv6 extension header +specification, and returns the extension header's updated total +length. +The +.Fa offset +argument should be the length returned by +.Fn inet6_opt_init +or +.Fn inet6_opt_append . +When +.Fa extbuf +is not +.Dv NULL +the function also sets up the appropriate padding bytes by inserting a +Pad1 or PadN option of the proper length. +.Pp +If the extension header is too small to contain the proper padding +then an error of \-1 is returned to the caller. +.\" +.Ss inet6_opt_set_val +The +.Fn inet6_opt_set_val +function inserts data items of various sizes into the data portion of +the option. +The +.Fa databuf +argument is a pointer to memory that was returned by the +.Fn inet6_opt_append +call and the +.Fa offset argument specifies where the option should be placed in the +data buffer. +The +.Fa val +argument points to an area of memory containing the data to be +inserted into the extension header, and the +.Fa vallen +argument indicates how much data to copy. +.Pp +The caller should ensure that each field is aligned on its natural +boundaries as described in Appendix B of RFC2460. +.Pp +The function returns the offset for the next field which is calculated as +.Fa offset ++ +.Fa vallen +and is used when composing options with multiple fields. +.\" +.Ss inet6_opt_next +The +.Fn inet6_opt_next +function parses received extension headers. +The +.Fa extbuf +and +.Fa extlen +arguments specify the location and length of the extension header +being parsed. +The +.Fa offset +argument should either be zero, for the first option, or the length value +returned by a previous call to +.Fn inet6_opt_next +or +.Fn inet6_opt_find . +The return value specifies the position where to continue scanning the +extension buffer. +The option is returned in the arguments +.Fa typep , lenp , +and +.Fa databufp . +.Fa typep, lenp, +and +.Fa databufp +point to the 8-bit option type, the 8-bit option length and the option +data respectively. +This function does not return any PAD1 or PADN options. +When an error occurs or there are no more options the return +value is \-1. +.\" +.Ss inet6_opt_find +The +.Fn inet6_opt_find +function searches the extension buffer for a particular option type, +passed in through the +.Fa type +argument. +If the option is found then the +.Fa lenp +and +.Fa databufp +arguments are updated to point to the option's length and data +respectively. +.Fa extbuf +and +.Fa extlen +must point to a valid extension buffer and give its length. +The +.Fa offset +argument can be used to search from a location anywhere in the +extension header. +.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 +is a pointer returned by the +.Fn inet6_opt_next +or +.Fn inet6_opt_find +functions. +The +.Fa val +argument points where the data will be extracted. +The +.Fa offset +argument specifies from where in the data portion of the option the +value should be extracted; the first byte of option data is specified +by an offset of zero. +.Pp +It is expected that each field is aligned on its natural boundaries as +described in Appendix B of RFC2460. +.Pp +The function returns the offset for the next field +by calculating +.Fa offset ++ +.Fa vallen +which can be used when extracting option content with multiple fields. +Robust receivers must verify alignment before calling this function. +.\" +.Sh DIAGNOSTICS +All the functions return +\-1 +on an error. +.\" +.Sh EXAMPLES +RFC3542 gives comprehensive examples in Section 23. +.Pp +KAME also provides examples in the +.Pa advapitest +directory of its kit. +.\" +.Sh SEE ALSO +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%A T. Jinmei +.%T "Advanced Sockets API for IPv6" +.%N RFC3542 +.%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 HISTORY +The implementation first appeared in KAME advanced networking kit. +.Sh STANDARDS +The functions are documented in +.Dq Advanced Sockets API for IPv6 +.Pq RFC3542 . +.\" diff --git a/lib/libc/net/inet6_option_space.3 b/lib/libc/net/inet6_option_space.3 new file mode 100644 index 0000000..c6bf1b5 --- /dev/null +++ b/lib/libc/net/inet6_option_space.3 @@ -0,0 +1,434 @@ +.\" $KAME: inet6_option_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (C) 2004 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. +.\" +.Dd December 23, 2004 +.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 Option 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 +.\" +Manipulating and parsing IPv6's Hop-by-Hop and Destination options is +complicated by the need to properly align and pad data as well as the +need to manipulate ancillary information that is not part of the data +stream. +RFC2292 defines a set of functions, which are implemented as +part of the Kame libraries, to support help developers create, change, +and parse Hop-by-Hope and Destination options. +All of the prototypes +for the option functions are defined in the +.In netinet/in.h +header file. +.\" +.Ss inet6_option_space +In order to determine the amount of space necessary to hold any option +the +.Fn inet6_option_space +function is called. +It 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 necessary padding at the end. +The +.Li nbytes +argument indicates the size of the structure defining the option, +and 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, the +.Fn inet6_option_space +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. +Usually this has +no impact because it is assumed that most Hop-by-Hop and Destination +option headers carry only one option as indicated in appendix B of RFC2460. +.\" +.Ss inet6_option_init +The +.Fn inet6_option_init +function is called to initialize any ancillary data object that will contain +a Hop-by-Hop or Destination option. +It returns +.Li 0 +on success and +.Li -1 +when an error occurs. +.Pp +The +.Fa bp +argument points to a previously allocated area of memory which must be +large enough to contain all the arguments that the application indents +to add later via +.Fn inet6_option_append +and +.Fn inet6_option_alloc +routines. +.Pp +The +.Fa cmsgp +argument is a pointer to a pointer to a +.Li cmsghdr +structure. +The +.Fa *cmsgp +argument +points to a +.Li cmsghdr +structure which is constructed by this function and stored in the +area of memory pointed to by +.Fa bp . +.Pp +The +.Fa type +is either +.Dv IPV6_HOPOPTS +or +.Dv IPV6_DSTOPTS +and is stored in the +.Li cmsg_type +member of the +.Li cmsghdr +structure mentioned above. +.\" +.Ss inet6_option_append +This function appends a Hop-by-Hop option or a Destination option into +an ancillary data object previously initialized by a call to +.Fn inet6_option_init . +The +.Fn inet6_option_append function returns +.Li 0 +if it succeeds or +.Li -1 +when an error occurs. +.Pp +The +.Fa cmsg +argument is a pointer to the +.Li cmsghdr +structure that was initialized by a call to +.Fn inet6_option_init . +.Pp +The +.Fa typep +argument is a pointer to the 8-bit option type. +All options are +encoded as type-length-value tuples and it is assumed that +the +.Fa typep +field is immediately followed by the 8-bit option data length field, +which is then followed by the option data. +.Pp +The option types of +.Li 0 +and +.Li 1 are reserved for the +.Li Pad1 +and +.Li PadN +options respectively. +All other values from +.Li 2 +through +.Li 255 +are available for applications to use. +.Pp +The option data length, since it is stored in 8 bites, must have a +value between +.Li 0 +and +.Li 255 , +inclusive. +.Pp +The +.Fa multx +argument +is the value +.Li x +in the alignment term +.Dq Li xn + y +and indicates the byte alignment necessary for the data. +Alignments may be specified as +.Li 1 , +.Li 2 , +.Li 4 , +or +.Li 8 +bytes, which is no alignment, 16 bit, 32 bit and 64 bit alignments +respectively. +.Pp +The +.Fa plusy +argument +is the value +.Li y +in the alignment term +.Dq Li xn + y +and must have a value between +.Li 0 +and +.Li 7 , +inclusive, indicating the amount of padding that is necessary for an +option. +.\" +.Ss inet6_option_alloc +The +.Fn inet6_option_alloc +function appends a Hop-by-Hop option or a Destination option into an +ancillary data object that has previously been initialized by a call to +.Fn inet6_option_init . +The +.Fn inet6_option_alloc +function returns a pointer to the 8-bit option type field that at the +beginning of the allocated the option on success, or +.Dv NULL +on an error. +.Pp +The difference between the +.Fn inet6_option_alloc +and +.Fn inet6_option_append +functions is that the latter copies the contents of a previously built +option into the ancillary data object while the former returns a +pointer to the place in the data object where the option's TLV must +then be built by the application. +.Pp +The +.Fa cmsg +argument is a pointer to a +.Li cmsghdr +structure that was 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 +and +.Fa plusy +arguments +are identical to the arguments of the same name described in the +.Fn inet6_option_init +function above. +.\" +.Ss inet6_option_next +The +.Fn inet6_option_next +function is used to process Hop-by-Hop and Destination options that +are present in an ancillary data object. +When an option remains to +be processed, the return value of the +.Fn inet6_option_next +function is +.Li 0 +and the +.Fa *tptrp +argument points to the 8-bit option type field, which is followed by +the 8-bit option data length, and then the option data. +When no more +options remain to be processed, the return value is +.Li -1 +and +.Fa *tptrp +is +.Dv NULL +and when an error occurs, the return value is +.Li -1 +but the +.Fa *tptrp +argument is not +.Dv NULL . +This set of return values allows a program to easily loop through all +the options in an ancillary data object, checking for the error and +end of stream conditions along the way. +.Pp +When a valid option is returned the +.Fa cmsg +argument points to a +.Li cmsghdr +where the +.Li cmsg_level +equals +.Dv IPPROTO_IPV6 +and +.Li cmsg_type +is 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. +When the +.Fn inet6_option_next +function is called for the first time on a given ancillary data object, +.Fa *tptrp +must be set to +.Dv NULL . +.Pp +Each time the function returns success, +the +.Fa *tptrp +argument points to the 8-bit option type field for the next option to +be processed. +.\" +.Ss inet6_option_find +The +.Fn inet6_option_find +function allows an application to search for a particular option type +in an ancillary data object. +The +.Fa cmsg +argument is a pointer to +.Li cmsghdr +structure in which the +.Li cmsg_level +element equals +.Dv IPPROTO_IPV6 +and the +.Li cmsg_type +element is either +.Dv IPV6_HOPOPTS +or +.Dv IPV6_DSTOPTS . +.Pp +The +.Fa tptrp +argument is handled exactly as in the +.Fn inet6_option_next +function described above. +.Pa +The +.fn inet6_option_find +function starts searching for an option of the specified type +beginning after the value of +.Fa *tptrp . +.\" +.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 +When +.Fn inet6_option_next +or +.Fn inet6_option_find +detect an error they return +.Li -1 +setting +.Fa *tptrp +to non +.Dv NULL +value. +.\" +.Sh EXAMPLES +RFC2292 gives comprehensive examples in chapter 6. +.\" +.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 HISTORY +The implementation first appeared in KAME advanced networking kit. +.\" +.Sh STANDARDS +The functions are documented in +.Dq Advanced Sockets API for IPv6 +(RFC2292). +.\" diff --git a/lib/libc/net/inet6_rth_space.3 b/lib/libc/net/inet6_rth_space.3 new file mode 100644 index 0000000..da26907 --- /dev/null +++ b/lib/libc/net/inet6_rth_space.3 @@ -0,0 +1,223 @@ +.\" $KAME: inet6_rth_space.3,v 1.7 2005/01/05 03:00:44 itojun Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (C) 2004 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. +.\" +.Dd December 24, 2004 +.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, RFC 3542, defines the functions that an +application calls to build and examine IPv6 Routing headers. +Routing headers are used to perform source routing in IPv6 networks. +The RFC uses the word +.Dq segments +to describe addresses and that is the term used here as well. +All of the functions are defined in the +.In netinet/in.h +header file. +The functions described in this manual page all operate +on routing header structures which are defined in +.In netinet/ip6.h +but which should not need to be modified outside the use of this API. +The size and shape of the route header structures may change, so using +the APIs is a more portable, long term, solution. +.Pp +The functions in the API are split into two groups, those that build a +routing header and those that parse a received routing header. +We will describe the builder functions followed by the parser functions. +.Ss inet6_rth_space +The +.Fn inet6_rth_space +function returns the number of bytes required to hold a Routing Header +of the type, specified in the +.Fa type +argument and containing the number of addresses specified in the +.Fa segments +argumment. +When the type is +.Dv IPV6_RTHDR_TYPE_0 +the number of segments must be from 0 through 127. +Routing headers of type +.Dv IPV6_RTHDR_TYPE_2 +contain only one segment, and are only used with Mobile IPv6. +The return value from this function is the number of bytes required to +store the routing header. +If the value 0 is returned then either the +route header type was not recognized or another error occurred. +.Ss inet6_rth_init +The +.Fn inet6_rth_init +function initializes the pre-allocated buffer pointed to by +.Fa bp +to contain a routing header of the specified type The +.Fa bp_len +argument is used to verify that the buffer is large enough. +The caller must allocate the buffer pointed to by bp. +The necessary buffer size should be determined by calling +.Fn inet6_rth_space +described in the previous sections. +.Pp +The +.Fn inet6_rth_init +function returns a pointer to +.Fa bp +on success and +.Dv NULL +when there is an error. +.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 +A successful addition results in the function returning 0, otherwise +\-1 is returned. +.Ss inet6_rth_reverse +The +.Fn inet6_rth_reverse +function takes a routing header, pointed to by the +argument +.Fa in , +and writes a new routing header into the argument pointed to by +.Fa out . +The routing header at that sends datagrams along the reverse of that +route. +Both arguments are allowed to point to the same buffer meaning +that the reversal can occur in place. +.Pp +The return value of the function is 0 on success, or \-1 when +there is an error. +.\" +.Pp +The next set of functions operate on a routing header that the +application wants to parse. +In the usual case such a routing header +is received from the network, although these functions can also be +used with routing headers that the application itself created. +.Ss inet6_rth_segments +The +.Fn inet6_rth_segments +function returns the number of segments contained in the +routing header pointed to by +.Fa bp . +The return value is the number of segments contained in the routing +header, or \-1 if an error occurred. +It is not an error for 0 to be +returned as a routing header may contain 0 segments. +.\" +.Ss inet6_rth_getaddr +The +.Fn inet6_rth_getaddr +function is used to retrieve a single address from a routing header. +The +.Fa index +is the location in the routing header from which the application wants +to retrieve an address. +The +.Fa index +parameter must have a value between 0 and one less than the number of +segments present in the routing header. +The +.Fn inet6_rth_segments +function, described in the last section, should be used to determine +the total number of segments in the routing header. +The +.Fn inet6_rth_getaddr +function returns a pointer to an IPv6 address on success or +.Dv NULL +when an error has occurred. +.\" +.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 EXAMPLES +RFC 3542 gives extensive examples in Section 21, Appendix B. +.Pp +KAME also provides examples in the advapitest directory of its kit. +.\" +.Sh SEE ALSO +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%A T. Jinmei +.%T "Advanced Sockets API for IPv6" +.%N RFC 3542 +.%D May 2003 +.Re +.Rs +.%A S. Deering +.%A R. Hinden +.%T "Internet Protocol, Version 6 (IPv6) Specification" +.%N RFC2460 +.%D December 1998 +.Re +.Sh HISTORY +The implementation first appeared in KAME advanced networking kit. diff --git a/lib/libc/net/inet6_rthdr_space.3 b/lib/libc/net/inet6_rthdr_space.3 new file mode 100644 index 0000000..bd49243 --- /dev/null +++ b/lib/libc/net/inet6_rthdr_space.3 @@ -0,0 +1,305 @@ +.\" $KAME: inet6_rthdr_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (C) 2004 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. +.\" +.Dd December 27, 2004 +.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 +.\"The RFC 2292 IPv6 Advanced API has been deprecated in favor of the +.\"newer, RFC 3542 APIs. +.\"On platforms that support it, currently only +.\"FreeBSD, please use the newer API to manipulate routing header +.\"options. +.\".Pp +The RFC 2292 IPv6 Advanced API defined eight functions for +applications to use for building and parsing routing headers. +The +eight functions are split into two groups, the first of which builds +the header and the second of which can parse it. +The function prototypes for these functions are all in the +.In netinet/in.h +header. +Although direct manipulation of a routing header is possible +this set of APIs make it unnecessary and such direct manipulation +should be avoided so that changes to the underlying structures do not +break applications. +.Pp +Please note that RFC 2292 uses the term +.Dq segments +instead of the term +.Dq addresses +but they are considered equivalent for this manual page. +.\" +.Ss inet6_rthdr_space +The +.Fn inet6_rthdr_space +function returns the number of bytes required to hold a routing header +of the specified +.Fa type +and containing the specified number of +.Fa segments . +Only one +.Fa type +is supported, +.Dv IPV6_RTHDR_TYPE_0 , +and it can hold from 1 to 23 segments. +The return value includes the +size of the cmsghdr structure that precedes the routing header, and +any required padding. +.Pp +A return value of 0 indicates an error. +Either the type was specified +incorrectly, or the number of segments was less than one or greater +than 23. +.Pp +Note: The +.Fn inet6_rthdr_space +function only returns the size required by the routing header and does +not allocate memory for the caller. +.\" +.Ss inet6_rthdr_init +The +.Fn inet6_rthdr_init +function initializes a buffer, pointed to by +.Fa bp +with an appropriate +.Li cmsghdr +structure followed by a routing header of the specified +.Fa type . +.Pp +The caller must use the +.Fn inet6_rthdr_space +function to determine the size of the buffer, and then allocate that +buffer before calling +.Fn inet6_rthdr_init . +.Pp +The return value is a pointer to a +.Li cmsghdr +structure, which is used as the first argument to the +.Fn inet6_rthdr_add +and +.Fn inet6_rthdr_lasthop +functions in order to construct the routing header. +When an error occurs the return value is +.Dv NULL . +.\" +.Ss inet6_rthdr_add +The +.Fn inet6_rthdr_add +function adds the IPv6 address pointed to by +.Fa addr +to the end of the +routing header being constructed and sets the type of this address to the +value of +.Fa flags . +The +.Fa flags +must be either +.Dv IPV6_RTHDR_LOOSE +or +.Dv IPV6_RTHDR_STRICT +indicating whether loose or strict source routing is required. +.Pp +When the function succeeds it returns 0, otherwise \-1 is returned. +.\" +.Ss inet6_rthdr_lasthop +The +.Fn inet6_rthdr_lasthop +function specifies the strict or loose flag for the final hop of a +routing header. +The +.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, and \-1 when an +error has occurred. +.Pp +Please note that a routing header specifying +.Li N +intermediate nodes requires +.Li N+1 +strict or loose flags meaning that +.Fn inet6_rthdr_add +must be called +.Li N +times and then +.Fn inet6_rthdr_lasthop +must be called once. +.\" +.Ss inet6_rthdr_reverse +This function was never implemented. +.Pp +The following four functions provide an API for parsing a received +routing header. +.\" +.Ss inet6_rthdr_segments +The +.Fn inet6_rthdr_segments +function returns the number of segments contained in the Routing +header pointed to by the +.Fa cmsg +argument. +On success the return value is from 1 to 23. +When an error occurs \-1 is returned. +.\" +.Ss inet6_rthdr_getaddr +The +.Fn inet6_rthdr_getaddr +function returns a pointer to the IPv6 address specified by the +.Fa index +argument from the routing header pointed to by +.Fa cmsg . +The index must be between 1 and the number returned by +.Fn inet6_rthdr_segments +described above. +An application must call +.Fn inet6_rthdr_segments +to obtain the number of segments in the routing header. +.Pp +If an error occurs the +.Dv NULL +is returned. +.\" +.Ss inet6_rthdr_getflags +The +.Fn inet6_rthdr_getflags +function returns the flags value of the segment specified by +.Fa index +of the routing header pointed to by +.Fa cmsg . +The +.Fa index +argument must be between 0 and the value returned by +.Fn inet6_rthdr_segments . +The return value will be either +.Dv IPV6_RTHDR_LOOSE +or +.Dv IPV6_RTHDR_STRICT +indicating whether loose or strict source routing was requested for +that segment. +.Pp +When an error occurs \-1 is returned. +.Pp +Note: Flags begin at index 0 while segments begin at index 1, to +maintain consistency with the terminology and figures in RFC2460. +.\" +.Sh DIAGNOSTICS +The +.Fn inet6_rthdr_space +function returns 0 when an error occurs. +.Pp +The +.Fn inet6_rthdr_add , +.Fn inet6_rthdr_lasthop +functions return 0 on success, and \-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 EXAMPLES +RFC2292 gives comprehensive examples in chapter 8. +.\" +.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 HISTORY +The implementation first appeared in KAME advanced networking kit. +.\" +.Sh BUGS +The +.Fn inet6_rthdr_reverse +function was never implemented. +.\".Pp +.\"This API is deprecated in favor of +.\".Xr inet6_rth_space 3 +.\".Sh SEE ALSO +.\".Xr inet6_rth_space 3 diff --git a/share/man/man4/icmp6.4 b/share/man/man4/icmp6.4 new file mode 100644 index 0000000..c2f786f --- /dev/null +++ b/share/man/man4/icmp6.4 @@ -0,0 +1,255 @@ +.\" $KAME: icmp6.4,v 1.6 2004/12/27 05:30:56 itojun Exp $ +.\" $OpenBSD: icmp6.4,v 1.19 2004/12/23 20:33:03 jaredy Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.Dd December 20, 2004 +.Dt ICMP6 4 +.Os +.Sh NAME +.Nm icmp6 +.Nd Internet Control Message Protocol for IPv6 +.Sh SYNOPSIS +.In sys/socket.h +.In netinet/in.h +.In netinet/icmp6.h +.Ft int +.Fn socket AF_INET6 SOCK_RAW IPPROTO_ICMPV6 +.Sh DESCRIPTION +ICMPv6 is the error and control message protocol used by IPv6 and the +IPv6 protocol family (see +.Xr ip6 4 +and +.Xr inet6 4 ) . +It may be accessed through a +.Dq raw socket +for network monitoring and diagnostic functions. +.Pp +The +.Fa proto +parameter to the +.Xr socket 2 +call to create an ICMPv6 socket may be obtained from +.Xr getprotobyname 3 . +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 +.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 IPv6 header prepended to them +(based on the destination address). +Incoming packets on the socket are received with the IPv6 header and any +extension headers removed. +.Ss Types +ICMPv6 messages are classified according to the type and code fields +present in the ICMPv6 header. +The abbreviations for the types and codes may be used in rules in +.Xr pf.conf 5 . +The following types are defined: +.Bl -column x xxxxxxxxxxxx -offset indent +.It Sy Num Ta Sy Abbrev. Ta Sy Description +.It 1 Ta unreach Ta "Destination unreachable" +.It 2 Ta toobig Ta "Packet too big" +.It 3 Ta timex Ta "Time exceeded" +.It 4 Ta paramprob Ta "Invalid IPv6 header" +.It 128 Ta echoreq Ta "Echo service request" +.It 129 Ta echorep Ta "Echo service reply" +.It 130 Ta groupqry Ta "Group membership query" +.It 130 Ta listqry Ta "Multicast listener query" +.It 131 Ta grouprep Ta "Group membership report" +.It 131 Ta listenrep Ta "Multicast listener report" +.It 132 Ta groupterm Ta "Group membership termination" +.It 132 Ta listendone Ta "Multicast listerner done" +.It 133 Ta routersol Ta "Router solicitation" +.It 134 Ta routeradv Ta "Router advertisement" +.It 135 Ta neighbrsol Ta "Neighbor solicitation" +.It 136 Ta neighbradv Ta "Neighbor advertisement" +.It 137 Ta redir Ta "Shorter route exists" +.It 138 Ta routrrenum Ta "Route renumbering" +.It 139 Ta fqdnreq Ta "FQDN query" +.It 139 Ta niqry Ta "Node information query" +.It 139 Ta wrureq Ta "Who-are-you request" +.It 140 Ta fqdnrep Ta "FQDN reply" +.It 140 Ta nirep Ta "Node information reply" +.It 140 Ta wrurep Ta "Who-are-you reply" +.It 200 Ta mtraceresp Ta "mtrace response" +.It 201 Ta mtrace Ta "mtrace messages" +.El +.Pp +The following codes are defined: +.Bl -column x xxxxxxxxxxxx xxxxxxxx -offset indent +.It Sy Num Ta Sy Abbrev. Ta Sy Type Ta +.Sy Description +.It 0 Ta noroute-unr Ta unreach Ta "No route to destination" +.It 1 Ta admin-unr Ta unreach Ta "Administratively prohibited" +.It 2 Ta beyond-unr Ta unreach Ta "Beyond scope of source address" +.It 2 Ta notnbr-unr Ta unreach Ta "Not a neighbor (obselete)" +.It 3 Ta addr-unr Ta unreach Ta "Address unreachable" +.It 4 Ta port-unr Ta unreach Ta "Port unreachable" +.It 0 Ta transit Ta timex Ta "Time exceeded in transit" +.It 1 Ta reassemb Ta timex Ta "Time exceeded in reassembly" +.It 0 Ta badhead Ta paramprob Ta "Erroneous header field" +.It 1 Ta nxthdr Ta paramprob Ta "Unrecognized next header" +.It 2 Ta "" Ta redir Ta "Unrecognized option" +.It 0 Ta redironlink Ta redir Ta "Redirection to on-link node" +.It 1 Ta redirrouter Ta redir Ta "Redirection to better router" +.El +.Ss Headers +All ICMPv6 messages are prefixed with an ICMPv6 header. +This header corresponds to the +.Vt icmp6_hdr +structure and has the following definition: +.Bd -literal -offset indent +struct icmp6_hdr { + u_int8_t icmp6_type; /* type field */ + u_int8_t icmp6_code; /* code field */ + u_int16_t icmp6_cksum; /* checksum field */ + union { + u_int32_t icmp6_un_data32[1]; /* type-specific */ + u_int16_t icmp6_un_data16[2]; /* type-specific */ + u_int8_t icmp6_un_data8[4]; /* type-specific */ + } icmp6_dataun; +} __packed; + +#define icmp6_data32 icmp6_dataun.icmp6_un_data32 +#define icmp6_data16 icmp6_dataun.icmp6_un_data16 +#define icmp6_data8 icmp6_dataun.icmp6_un_data8 +#define icmp6_pptr icmp6_data32[0] /* parameter prob */ +#define icmp6_mtu icmp6_data32[0] /* packet too big */ +#define icmp6_id icmp6_data16[0] /* echo request/reply */ +#define icmp6_seq icmp6_data16[1] /* echo request/reply */ +#define icmp6_maxdelay icmp6_data16[0] /* mcast group membership*/ +.Ed +.Pp +.Va icmp6_type +describes the type of the message. +Suitable values are defined in +.Aq Pa netinet/icmp6.h . +.Va icmp6_code +describes the sub-type of the message and depends on +.Va icmp6_type . +.Va icmp6_cksum +contains the checksum for the message and is filled in by the +kernel on outgoing messages. +The other fields are used for type-specific purposes. +.Ss Filters +Because of the extra functionality of ICMPv6 in comparison to ICMPv4, +a larger number of messages may be potentially received on an ICMPv6 +socket. +Input filters may therefore be used to restrict input to a subset of the +incoming ICMPv6 messages so only interesting messages are returned by the +.Xr recv 2 +family of calls to an application. +.Pp +The +.Vt icmp6_filter +structure may be used to refine the input message set according to the +ICMPv6 type. +By default, all messages types are allowed on newly created raw ICMPv6 +sockets. +The following macros may be used to refine the input set: +.Bl -tag -width Ds +.It Fn "void ICMP6_FILTER_SETPASSALL" "struct icmp6_filter *filterp" +Allow all incoming messages. +.Va filterp +is modified to allow all message types. +.It Fn "void ICMP6_FILTER_SETBLOCKALL" "struct icmp6_filter *filterp" +Ignore all incoming messages. +.Va filterp +is modified to ignore all message types. +.It Fn "void ICMP6_FILTER_SETPASS" "int type" \ + "struct icmp6_filter *filterp" +Allow ICMPv6 messages with the given +.Fa type . +.Va filterp +is modified to allow such messages. +.It Fn "void ICMP6_FILTER_SETBLOCK" "int type" \ + "struct icmp6_filter *filterp" +Ignore ICMPv6 messages with the given +.Fa type . +.Va filterp +is modified to ignore such messages. +.It Fn "int ICMP6_FILTER_WILLPASS" "int type" \ + "const struct icmp6_filter *filterp" +Determine if the given filter will allow an ICMPv6 message of the given +type. +.It Fn "int ICMP6_FILTER_WILLBLOCK" "int type" \ + "const struct icmp6_filter *filterp" +Determine if the given filter will ignore an ICMPv6 message of the given +type. +.El +.Pp +The +.Xr getsockopt 2 +and +.Xr setsockopt 2 +calls may be used to obtain and install the filter on ICMPv6 sockets at +option level +.Dv IPPROTO_ICMPV6 +and name +.Dv ICMPV6_FILTER +with a pointer to the +.Vt icmp6_filter +structure as the option value. +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr setsockopt 2 , +.Xr socket 2 , +.Xr getprotobyname 3 , +.Xr inet6 4 , +.Xr ip6 4 , +.Xr netintro 4 +.Rs +.%A W. Stevens +.%A M. Thomas +.%T Advanced Sockets API for IPv6 +.%N RFC 2292 +.%D February 1998 +.Re +.Rs +.%A A. Conta +.%A S. Deering +.%T "Internet Control Message Protocol (ICMPv6) for the Internet" \ + "Protocol Version 6 (IPv6) Specification" +.%N RFC 2463 +.%D December 1998 +.Re diff --git a/share/man/man4/ip6.4 b/share/man/man4/ip6.4 new file mode 100644 index 0000000..521c7f4 --- /dev/null +++ b/share/man/man4/ip6.4 @@ -0,0 +1,686 @@ +.\" $KAME: ip6.4,v 1.23 2005/01/11 05:56:25 itojun Exp $ +.\" $OpenBSD: ip6.4,v 1.21 2005/01/06 03:50:46 itojun Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.Dd December 29, 2004 +.Dt IP6 4 +.Os +.Sh NAME +.Nm ip6 +.Nd Internet Protocol version 6 (IPv6) network layer +.Sh SYNOPSIS +.In sys/socket.h +.In netinet/in.h +.Ft int +.Fn socket AF_INET6 SOCK_RAW proto +.Sh DESCRIPTION +The IPv6 network layer is used by the IPv6 protocol family for +transporting data. +IPv6 packets contain an IPv6 header that is not provided as part of the +payload contents when passed to an application. +IPv6 header options affect the behavior of this protocol and may be used +by high-level protocols (such as the +.Xr tcp 4 +and +.Xr udp 4 +protocols) as well as directly by +.Dq raw sockets , +which process IPv6 messages at a lower-level and may be useful for +developing new protocols and special-purpose applications. +.Ss Header +All IPv6 packets begin with an IPv6 header. +When data received by the kernel are passed to the application, this +header is not included in buffer, even when raw sockets are being used. +Likewise, when data are sent to the kernel for transmit from the +application, the buffer is not examined for an IPv6 header: +the kernel always constructs the header. +To directly access IPv6 headers from received packets and specify them +as part of the buffer passed to the kernel, link-level access +.Po +.Xr bpf 4 , +for example +.Pc +must instead be utilized. +.Pp +The header has the following definition: +.Bd -literal -offset indent +struct ip6_hdr { + union { + struct ip6_hdrctl { + u_int32_t ip6_un1_flow; /* 20 bits of flow ID */ + u_int16_t ip6_un1_plen; /* payload length */ + u_int8_t ip6_un1_nxt; /* next header */ + u_int8_t ip6_un1_hlim; /* hop limit */ + } ip6_un1; + u_int8_t ip6_un2_vfc; /* version and class */ + } ip6_ctlun; + struct in6_addr ip6_src; /* source address */ + struct in6_addr ip6_dst; /* destination address */ +} __packed; + +#define ip6_vfc ip6_ctlun.ip6_un2_vfc +#define ip6_flow ip6_ctlun.ip6_un1.ip6_un1_flow +#define ip6_plen ip6_ctlun.ip6_un1.ip6_un1_plen +#define ip6_nxt ip6_ctlun.ip6_un1.ip6_un1_nxt +#define ip6_hlim ip6_ctlun.ip6_un1.ip6_un1_hlim +#define ip6_hops ip6_ctlun.ip6_un1.ip6_un1_hlim +.Ed +.Pp +All fields are in network-byte order. +Any options specified (see +.Sx Options +below) must also be specified in network-byte order. +.Pp +.Va ip6_flow +specifies the flow ID. +.Va ip6_plen +specifies the payload length. +.Va ip6_nxt +specifies the type of the next header. +.Va ip6_hlim +specifies the hop limit. +.Pp +The top 4 bits of +.Va ip6_vfc +specify the class and the bottom 4 bits specify the version. +.Pp +.Va ip6_src +and +.Va ip6_dst +specify the source and destination addresses. +.Pp +The IPv6 header may be followed by any number of extension headers that start +with the following generic definition: +.Bd -literal -offset indent +struct ip6_ext { + u_int8_t ip6e_nxt; + u_int8_t ip6e_len; +} __packed; +.Ed +.Ss Options +IPv6 allows header options on packets to manipulate the behavior of the +protocol. +These options and other control requests are accessed with the +.Xr getsockopt 2 +and +.Xr setsockopt 2 +system calls at level +.Dv IPPROTO_IPV6 +and by using ancillary data in +.Xr recvmsg 2 +and +.Xr sendmsg 2 . +They can be used to access most of the fields in the IPv6 header and +extension headers. +.Pp +The following socket options are supported: +.Bl -tag -width Ds +.\" .It Dv IPV6_OPTIONS +.It Dv IPV6_UNICAST_HOPS Fa "int *" +Get or set the default hop limit header field for outgoing unicast +datagrams sent on this socket. +A value of \-1 resets to the default value. +.\" .It Dv IPV6_RECVOPTS Fa "int *" +.\" Get or set the status of whether all header options will be +.\" delivered along with the datagram when it is received. +.\" .It Dv IPV6_RECVRETOPTS Fa "int *" +.\" Get or set the status of whether header options will be delivered +.\" for reply. +.\" .It Dv IPV6_RECVDSTADDR Fa "int *" +.\" Get or set the status of whether datagrams are received with +.\" destination addresses. +.\" .It Dv IPV6_RETOPTS +.\" Get or set IPv6 options. +.It Dv IPV6_MULTICAST_IF Fa "u_int *" +Get or set the interface from which multicast packets will be sent. +For hosts with multiple interfaces, each multicast transmission is sent +from the primary network interface. +The interface is specified as its index as provided by +.Xr if_nametoindex 3 . +A value of zero specifies the default interface. +.It Dv IPV6_MULTICAST_HOPS Fa "int *" +Get or set the default hop limit header field for outgoing multicast +datagrams sent on this socket. +This option controls the scope of multicast datagram transmissions. +.Pp +Datagrams with a hop limit of 1 are not forwarded beyond the local +network. +Multicast datagrams with a hop limit of zero 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 (see below) has not been +disabled on the sending socket. +Multicast datagrams with a hop limit greater than 1 may be forwarded to +the other networks if a multicast router (such as +.Xr mrouted 8 ) +is attached to the local network. +.It Dv IPV6_MULTICAST_LOOP Fa "u_int *" +Get or set the status of whether multicast datagrams will be looped back +for local delivery when a multicast datagram is sent to a group to which +the sending host belongs. +.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 hop limit 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 multicast loopback control option has no effect on such delivery. +.It Dv IPV6_JOIN_GROUP Fa "struct ipv6_mreq *" +Join a multicast group. +A host must become a member of a multicast group before it can receive +datagrams sent to the group. +.Bd -literal +struct ipv6_mreq { + struct in6_addr ipv6mr_multiaddr; + unsigned int ipv6mr_interface; +}; +.Ed +.Pp +.Va ipv6mr_interface +may be set to zeroes to choose the default multicast interface or to the +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 +If the multicast address is unspecified (i.e., all zeroes), messages +from all multicast addresses will be accepted by this group. +Note that setting to this value requires superuser privileges. +.It Dv IPV6_LEAVE_GROUP Fa "struct ipv6_mreq *" +Drop membership from the associated multicast group. +Memberships are automatically dropped when the socket is closed or when +the process exits. +.It Dv IPV6_PORTRANGE Fa "int *" +Get or set the allocation policy of ephemeral ports for when the kernel +automatically binds a local address to this socket. +The following values are available: +.Pp +.Bl -tag -width IPV6_PORTRANGE_DEFAULT -compact +.It Dv IPV6_PORTRANGE_DEFAULT +Use the regular range of non-reserved ports (varies, see +.Xr sysctl 8 ) . +.It Dv IPV6_PORTRANGE_HIGH +Use a high range (varies, see +.Xr sysctl 8 ) . +.It Dv IPV6_PORTRANGE_LOW +Use a low, reserved range (600\-1023). +.El +.It Dv IPV6_PKTINFO Fa "int *" +Get or set whether additional information about subsequent packets will +be provided as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The information is stored in the following structure in the ancillary +data returned: +.Bd -literal +struct in6_pktinfo { + struct in6_addr ipi6_addr; /* src/dst IPv6 address */ + unsigned int ipi6_ifindex; /* send/recv if index */ +}; +.Ed +.It Dv IPV6_HOPLIMIT Fa "int *" +Get or set whether the hop limit header field from subsequent packets +will be provided as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The value is stored as an +.Vt int +in the ancillary data returned. +.\" .It Dv IPV6_NEXTHOP Fa "int *" +.\" Get or set whether the address of the next hop for subsequent +.\" packets will be provided as ancillary data along with the payload in +.\" subsequent +.\" .Xr recvmsg 2 +.\" calls. +.\" The option is stored as a +.\" .Vt sockaddr +.\" structure in the ancillary data returned. +.\" .Pp +.\" This option requires superuser privileges. +.It Dv IPV6_HOPOPTS Fa "int *" +Get or set whether the hop-by-hop options from subsequent packets will be +provided as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The option is stored in the following structure in the ancillary data +returned: +.Bd -literal +struct ip6_hbh { + u_int8_t ip6h_nxt; /* next header */ + u_int8_t ip6h_len; /* length in units of 8 octets */ +/* followed by options */ +} __packed; +.Ed +.Pp +The +.Fn inet6_option_space +routine and family of routines may be used to manipulate this data. +.Pp +This option requires superuser privileges. +.It Dv IPV6_DSTOPTS Fa "int *" +Get or set whether the destination options from subsequent packets will +be provided as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The option is stored in the following structure in the ancillary data +returned: +.Bd -literal +struct ip6_dest { + u_int8_t ip6d_nxt; /* next header */ + u_int8_t ip6d_len; /* length in units of 8 octets */ +/* followed by options */ +} __packed; +.Ed +.Pp +The +.Fn inet6_option_space +routine and family of routines may be used to manipulate this data. +.Pp +This option requires superuser privileges. +.It Dv IPV6_RTHDR Fa "int *" +Get or set whether the routing header from subsequent packets will be +provided as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The header is stored in the following structure in the ancillary data +returned: +.Bd -literal +struct ip6_rthdr { + u_int8_t ip6r_nxt; /* next header */ + u_int8_t ip6r_len; /* length in units of 8 octets */ + u_int8_t ip6r_type; /* routing type */ + u_int8_t ip6r_segleft; /* segments left */ +/* followed by routing-type-specific data */ +} __packed; +.Ed +.Pp +The +.Fn inet6_option_space +routine and family of routines may be used to manipulate this data. +.Pp +This option requires superuser privileges. +.It Dv IPV6_PKTOPTIONS Fa "struct cmsghdr *" +Get or set all header options and extension headers at one time on the +last packet sent or received on the socket. +All options must fit within the size of an mbuf (see +.Xr mbuf 9 ) . +Options are specified as a series of +.Vt cmsghdr +structures followed by corresponding values. +.Va cmsg_level +is set to +.Dv IPPROTO_IPV6 , +.Va cmsg_type +to one of the other values in this list, and trailing data to the option +value. +When setting options, if the length +.Va optlen +to +.Xr setsockopt 2 +is zero, all header options will be reset to their default values. +Otherwise, the length should specify the size the series of control +messages consumes. +.Pp +Instead of using +.Xr sendmsg 2 +to specify option values, the ancillary data used in these calls that +correspond to the desired header options may be directly specified as +the control message in the series of control messages provided as the +argument to +.Xr setsockopt 2 . +.It Dv IPV6_CHECKSUM Fa "int *" +Get or set the byte offset into a packet where the 16-bit checksum is +located. +When set, this byte offset is where incoming packets will be expected +to have checksums of their data stored and where outgoing packets will +have checksums of their data computed and stored by the kernel. +A value of \-1 specifies that no checksums will be checked on incoming +packets and that no checksums will be computed or stored on outgoing +packets. +The offset of the checksum for ICMPv6 sockets cannot be relocated or +turned off. +.It Dv IPV6_V6ONLY Fa "int *" +Get or set whether only IPv6 connections can be made to this socket. +For wildcard sockets, this can restrict connections to IPv6 only. +.\"With +.\".Ox +.\"IPv6 sockets are always IPv6-only, so the socket option is read-only +.\"(not modifiable). +.It Dv IPV6_FAITH Fa "int *" +Get or set the status of whether +.Xr faith 4 +connections can be made to this socket. +.It Dv IPV6_USE_MIN_MTU Fa "int *" +Get or set whether the minimal IPv6 maximum transmission unit (MTU) size +will be used to avoid fragmentation from occurring for subsequent +outgoing datagrams. +.It Dv IPV6_AUTH_LEVEL Fa "int *" +Get or set the +.Xr ipsec 4 +authentication level. +.It Dv IPV6_ESP_TRANS_LEVEL Fa "int *" +Get or set the ESP transport level. +.It Dv IPV6_ESP_NETWORK_LEVEL Fa "int *" +Get or set the ESP encapsulation level. +.It Dv IPV6_IPCOMP_LEVEL Fa "int *" +Get or set the +.Xr ipcomp 4 +level. +.El +.Pp +The +.Dv IPV6_PKTINFO , +.\" .Dv IPV6_NEXTHOP , +.Dv IPV6_HOPLIMIT , +.Dv IPV6_HOPOPTS , +.Dv IPV6_DSTOPTS , +and +.Dv IPV6_RTHDR +options will return ancillary data along with payload contents in subsequent +.Xr recvmsg 2 +calls with +.Va cmsg_level +set to +.Dv IPPROTO_IPV6 +and +.Va cmsg_type +set to respective option name value (e.g., +.Dv IPV6_HOPTLIMIT ) . +These options may also be used directly as ancillary +.Va cmsg_type +values in +.Xr sendmsg 2 +to set options on the packet being transmitted by the call. +The +.Va cmsg_level +value must be +.Dv IPPROTO_IPV6 . +For these options, the ancillary data object value format is the same +as the value returned as explained for each when received with +.Xr recvmsg 2 . +.Pp +Note that using +.Xr sendmsg 2 +to specify options on particular packets works only on UDP and raw sockets. +To manipulate header options for packets on TCP sockets, only the socket +options may be used. +.Pp +In some cases, there are multiple APIs defined for manipulating an IPv6 +header field. +A good example is the outgoing interface for multicast datagrams, which +can be set by the +.Dv IPV6_MULTICAST_IF +socket option, through the +.Dv IPV6_PKTINFO +option, and through the +.Va sin6_scope_id +field of the socket address passed to the +.Xr sendto 2 +system call. +.Pp +Resolving these conflicts is implementation dependent. +This implementation determines the value in the following way: +options specified by using ancillary data (i.e., +.Xr sendmsg 2 ) +are considered first, +options specified by using +.Dv IPV6_PKTOPTIONS +to set +.Dq sticky +options are considered second, +options specified by using the individual, basic, and direct socket +options (e.g., +.Dv IPV6_UNICAST_HOPS ) +are considered third, +and options specified in the socket address supplied to +.Xr sendto 2 +are the last choice. +.Ss Multicasting +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. +Socket options (see above) that manipulate membership of +multicast groups and other multicast options include +.Dv IPV6_MULTICAST_IF , +.Dv IPV6_MULTICAST_HOPS , +.Dv IPV6_MULTICAST_LOOP , +.Dv IPV6_LEAVE_GROUP , +and +.Dv IPV6_JOIN_GROUP . +.Ss Raw Sockets +Raw IPv6 sockets are connectionless and are normally used with the +.Xr sendto 2 +and +.Xr recvfrom 2 +calls, although the +.Xr connect 2 +call may be used to fix the destination address for future outgoing +packets so that +.Xr send 2 +may instead be used and the +.Xr bind 2 +call may be used to fix the source address for future outgoing +packets instead of having the kernel choose a source address. +.Pp +By using +.Xr connect 2 +or +.Xr bind 2 , +raw socket input is constrained to only packets with their +source address matching the socket destination address if +.Xr connect 2 +was used and to packets with their destination address +matching the socket source address if +.Xr bind 2 +was used. +.Pp +If the +.Ar proto +argument to +.Xr socket 2 +is zero, the default protocol +.Pq Dv IPPROTO_RAW +is used for outgoing packets. +For incoming packets, protocols recognized by kernel are +.Sy not +passed to the application socket (e.g., +.Xr tcp 4 +and +.Xr udp 4 ) +except for some ICMPv6 messages. +The ICMPv6 messages not passed to raw sockets include echo, timestamp, +and address mask requests. +If +.Ar proto +is non-zero, only packets with this protocol will be passed to the +socket. +.Pp +IPv6 fragments are also not passed to application sockets until +they have been reassembled. +If reception of all packets is desired, link-level access (such as +.Xr bpf 4 ) +must be used instead. +.Pp +Outgoing packets automatically have an IPv6 header prepended to them +(based on the destination address and the protocol number the socket +was created with). +Incoming packets are received by an application without the IPv6 header +or any extension headers. +.Pp +Outgoing packets will be fragmented automatically by the kernel if they +are too large. +Incoming packets will be reassembled before being sent to the raw socket, +so packet fragments or fragment headers will never be seen on a raw socket. +.Sh EXAMPLES +The following determines the hop limit on the next packet received: +.Bd -literal +struct iovec iov[2]; +u_char buf[BUFSIZ]; +struct cmsghdr *cm; +struct msghdr m; +int found, optval; +u_char data[2048]; + +/* Create socket. */ + +(void)memset(&m, 0, sizeof(m)); +(void)memset(&iov, 0, sizeof(iov)); + +iov[0].iov_base = data; /* buffer for packet payload */ +iov[0].iov_len = sizeof(data); /* expected packet length */ + +m.msg_name = &from; /* sockaddr_in6 of peer */ +m.msg_namelen = sizeof(from); +m.msg_iov = iov; +m.msg_iovlen = 1; +m.msg_control = (caddr_t)buf; /* buffer for control messages */ +m.msg_controllen = sizeof(buf); + +/* + * Enable the hop limit value from received packets to be + * returned along with the payload. + */ +optval = 1; +if (setsockopt(s, IPPROTO_IPV6, IPV6_HOPLIMIT, &optval, + sizeof(optval)) == -1) + err(1, "setsockopt"); + +found = 0; +while (!found) { + if (recvmsg(s, &m, 0) == -1) + err(1, "recvmsg"); + for (cm = CMSG_FIRSTHDR(&m); cm != NULL; + cm = CMSG_NXTHDR(&m, cm)) { + if (cm->cmsg_level == IPPROTO_IPV6 && + cm->cmsg_type == IPV6_HOPLIMIT && + cm->cmsg_len == CMSG_LEN(sizeof(int))) { + found = 1; + (void)printf("hop limit: %d\en", + *(int *)CMSG_DATA(cm)); + break; + } + } +} +.Ed +.Sh DIAGNOSTICS +A socket operation may fail with one of the following errors returned: +.Bl -tag -width EADDRNOTAVAILxx +.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 IPv6 may occur when setting or getting +header options: +.Bl -tag -width EADDRNOTAVAILxx +.It Bq Er EINVAL +An unknown socket option name was given. +.It Bq Er EINVAL +An ancillary data object was improperly formed. +.El +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr setsockopt 2 , +.Xr socket 2 , +.\" .Xr inet6_option_space 3 , +.\" .Xr inet6_rthdr_space 3 , +.Xr if_nametoindex 3 , +.Xr bpf 4 , +.Xr icmp6 4 , +.Xr inet6 4 , +.Xr netintro 4 , +.Xr tcp 4 , +.Xr udp 4 +.Rs +.%A W. Stevens +.%A M. Thomas +.%T Advanced Sockets API for IPv6 +.%R RFC 2292 +.%D February 1998 +.Re +.Rs +.%A S. Deering +.%A R. Hinden +.%T Internet Protocol, Version 6 (IPv6) Specification +.%R RFC 2460 +.%D December 1998 +.Re +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A W. Stevens +.%T Basic Socket Interface Extensions for IPv6 +.%R RFC 2553 +.%D March 1999 +.Re +.Rs +.%A W. Stevens +.%A B. Fenner +.%A A. Rudoff +.%T UNIX Network Programming, third edition +.Re +.Sh STANDARDS +Most of the socket options are defined in RFC 2292 or RFC 2553. +The +.Dv IPV6_V6ONLY +socket option is defined in RFC 3542. +The +.Dv IPV6_PORTRANGE +socket option and the conflict resolution rule are not defined in the +RFCs and should be considered implementation dependent. |