From c6bc06c657d497ab7fa2d2422806fb933cd9f2fc Mon Sep 17 00:00:00 2001 From: gnn Date: Sun, 23 Jan 2005 16:02:48 +0000 Subject: Submitted by: George V. Neville-Neil (gnn at freebsd dot org) Reviewed by: Kame Project (including Itojun-san, Jinmei-san and Suzuki-san) Approved by: Robert Watson (robert at freebsd dot org) Obtained from: Kame Project and OpenBSD Replace manual pages that may have violated the IETF's Copyright. All come from the Kame tree. Several were from OpenBSD except for ip6.4, and the inet6* pages which were rewritten by me. All of the text is new and drawn from reading the code and documentation. --- lib/libc/net/gai_strerror.3 | 94 ++++++++ lib/libc/net/getaddrinfo.3 | 435 ++++++++++++++++++++++++++++++++++++++ lib/libc/net/getnameinfo.3 | 271 ++++++++++++++++++++++++ lib/libc/net/inet6_opt_init.3 | 337 +++++++++++++++++++++++++++++ lib/libc/net/inet6_option_space.3 | 434 +++++++++++++++++++++++++++++++++++++ lib/libc/net/inet6_rth_space.3 | 223 +++++++++++++++++++ lib/libc/net/inet6_rthdr_space.3 | 305 ++++++++++++++++++++++++++ 7 files changed, 2099 insertions(+) create mode 100644 lib/libc/net/gai_strerror.3 create mode 100644 lib/libc/net/getaddrinfo.3 create mode 100644 lib/libc/net/getnameinfo.3 create mode 100644 lib/libc/net/inet6_opt_init.3 create mode 100644 lib/libc/net/inet6_option_space.3 create mode 100644 lib/libc/net/inet6_rth_space.3 create mode 100644 lib/libc/net/inet6_rthdr_space.3 (limited to 'lib/libc') 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 +.Fd #include +.Fd #include +.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 +.Fd #include +.Fd #include +.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 +.Fd #include +.Fd #include +.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 -- cgit v1.1