IPv6 manpage, wrote from scratch. deraadt ok

5 files changed, 764 insertions, 16 deletions

diff --git a/src/lib/libc/net/gai_strerror.3 b/src/lib/libc/net/gai_strerror.3
index 06caac0993..d0a636ee03 100644
--- a/src/lib/libc/net/gai_strerror.3
+++ b/src/lib/libc/net/gai_strerror.3
@@ -1,4 +1,5 @@
-.\"     $OpenBSD: gai_strerror.3,v 1.4 2004/12/20 23:04:53 millert Exp $
+.\"     $OpenBSD: gai_strerror.3,v 1.5 2005/01/06 03:50:46 itojun Exp $
+.\"     $KAME: gai_strerror.3,v 1.1 2005/01/05 03:04:47 itojun Exp $
 .\"
 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
diff --git a/src/lib/libc/net/getaddrinfo.3 b/src/lib/libc/net/getaddrinfo.3
index 4fba44bb73..64f317c010 100644
--- a/src/lib/libc/net/getaddrinfo.3
+++ b/src/lib/libc/net/getaddrinfo.3
@@ -1,4 +1,5 @@
-.\"     $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $
+.\"     $OpenBSD: getaddrinfo.3,v 1.36 2005/01/06 03:50:46 itojun Exp $
+.\"     $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $
 .\"
 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
@@ -222,7 +223,8 @@ member points to a filled-in socket address structure of length
 .Pp
 This implementation of
 .Fn getaddrinfo
-allows experimental numeric IPv6 address notation with scope identifiers.
+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
@@ -248,7 +250,6 @@ on the link associated with the
 interface
 .Dc .
 .Pp
-The IPv6 implementation is still very experimental and non-standard.
 The current implementation assumes a one-to-one relationship between
 the interface and link, which is not necessarily true from the specification.
 .Pp
@@ -403,11 +404,14 @@ freeaddrinfo(res0);
 .%D February 2003
 .Re
 .Rs
-.%A Tatsuya Jinmei
-.%A Atsushi Onoe
-.%T "An Extension of Format for IPv6 Scoped Addresses"
+.%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-ipngwg-scopedaddr-format-02.txt
+.%N draft-ietf-ipv6-scoping-arch-02.txt
 .%O work in progress material
 .Re
 .Rs
diff --git a/src/lib/libc/net/getnameinfo.3 b/src/lib/libc/net/getnameinfo.3
index a6f2c63a91..39f9b8e14e 100644
--- a/src/lib/libc/net/getnameinfo.3
+++ b/src/lib/libc/net/getnameinfo.3
@@ -1,4 +1,5 @@
-.\"     $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc Exp $
+.\"     $OpenBSD: getnameinfo.3,v 1.37 2005/01/06 03:50:46 itojun Exp $
+.\"     $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $
 .\"
 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
@@ -115,8 +116,8 @@ and
 .Tn TCP .
 .El
 .Pp
-This implementation allows experimental numeric IPv6 address notation with
-scope identifier.
+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
@@ -177,11 +178,14 @@ printf("host=%s\en", hbuf);
 .%D March 1999
 .Re
 .Rs
-.%A Tatsuya Jinmei
-.%A Atsushi Onoe
-.%T "An Extension of Format for IPv6 Scoped Addresses"
+.%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-ipngwg-scopedaddr-format-02.txt
+.%N draft-ietf-ipv6-scoping-arch-02.txt
 .%O work in progress material
 .Re
 .Rs
@@ -255,7 +259,7 @@ if (error == 0) {
 .Ed
 .Sh BUGS
 The implementation of
-.Fn getaddrinfo
+.Fn getnameinfo
 is not thread-safe.
 .Pp
 .Ox
diff --git a/src/lib/libc/net/inet6_option_space.3 b/src/lib/libc/net/inet6_option_space.3
new file mode 100644
index 0000000000..9b5cac95e8
--- /dev/null
+++ b/src/lib/libc/net/inet6_option_space.3
@@ -0,0 +1,434 @@
+.\"     $OpenBSD: inet6_option_space.3,v 1.15 2005/01/06 03:50:46 itojun Exp $
+.\"     $KAME: inet6_option_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $
+.\"
+.\" 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/src/lib/libc/net/inet6_rthdr_space.3 b/src/lib/libc/net/inet6_rthdr_space.3
new file mode 100644
index 0000000000..77dbd64e3c
--- /dev/null
+++ b/src/lib/libc/net/inet6_rthdr_space.3
@@ -0,0 +1,305 @@
+.\"     $OpenBSD: inet6_rthdr_space.3,v 1.15 2005/01/06 03:50:46 itojun Exp $
+.\"     $KAME: inet6_rthdr_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $
+.\"
+.\" 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