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.

7 files changed, 2099 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