Import from KAME. Advanced API related function descriptions.

Obtained from: KAME project

3 files changed, 790 insertions, 1 deletions

diff --git a/lib/libc/net/Makefile.inc b/lib/libc/net/Makefile.inc
index cde2734..8e7df10 100644
--- a/lib/libc/net/Makefile.inc
+++ b/lib/libc/net/Makefile.inc
@@ -30,7 +30,8 @@ CFLAGS+=-DINET6
 MAN3+=	addr2ascii.3 byteorder.3 ethers.3 getaddrinfo.3 gethostbyname.3 \
 	getipnodebyname.3 \
 	getnameinfo.3 getnetent.3 getprotoent.3 getservent.3 if_indextoname.3 \
-	inet.3 linkaddr.3 rcmd.3 resolver.3
+	inet.3 inet6_option_space.3 inet6_rthdr_space.3 linkaddr.3 \
+	rcmd.3 resolver.3
 # not installed: iso_addr.3 ns.3
 
 MLINKS+=addr2ascii.3 ascii2addr.3
@@ -56,6 +57,18 @@ MLINKS+=inet.3 addr.3 inet.3 inet_addr.3 inet.3 inet_aton.3 \
 	inet.3 ntoa.3
 MLINKS+=if_indextoname.3 if_nametoindex.3 if_indextoname.3 if_nameindex.3 \
 	if_indextoname.3 if_freenameindex.3
+MLINKS+=inet6_option_space.3 inet6_option_alloc.3 \
+	inet6_option_space.3 inet6_option_append.3 \
+	inet6_option_space.3 inet6_option_find.3 \
+	inet6_option_space.3 inet6_option_init.3 \
+	inet6_option_space.3 inet6_option_next.3 \
+	inet6_rthdr_space.3 inet6_rthdr_add.3 \
+	inet6_rthdr_space.3 inet6_rthdr_getaddr.3 \
+	inet6_rthdr_space.3 inet6_rthdr_getflags.3 \
+	inet6_rthdr_space.3 inet6_rthdr_init.3 \
+	inet6_rthdr_space.3 inet6_rthdr_lasthop.3 \
+	inet6_rthdr_space.3 inet6_rthdr_reverse.3 \
+	inet6_rthdr_space.3 inet6_rthdr_segments.3
 MLINKS+=linkaddr.3 link_addr.3 linkaddr.3 link_ntoa.3 
 #MLINKS+=ns.3 ns_addr.3 ns.3 ns_ntoa.3
 MLINKS+=rcmd.3 iruserok.3 rcmd.3 rresvport.3 rcmd.3 ruserok.3 \
diff --git a/lib/libc/net/inet6_option_space.3 b/lib/libc/net/inet6_option_space.3
new file mode 100644
index 0000000..acb391e
--- /dev/null
+++ b/lib/libc/net/inet6_option_space.3
@@ -0,0 +1,450 @@
+.\" Copyright (c) 1983, 1987, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     $Id: inet6_option_space.3,v 1.4 2000/02/05 10:32:24 jinmei Exp $
+.\" $FreeBSD$
+.\"
+.Dd December 10, 1999
+.Dt INET6_OPTION_SPACE 3
+.Os KAME
+.\"
+.Sh NAME
+.Nm inet6_option_space ,
+.Nm inet6_option_init ,
+.Nm inet6_option_append ,
+.Nm inet6_option_alloc ,
+.Nm inet6_option_next ,
+.Nm inet6_option_find
+.Nd IPv6 Hop-by-Hop and Destination Options manipulation
+.\"
+.Sh SYNOPSIS
+.Fd #include <netinet/in.h>
+.Ft "int"
+.Fn inet6_options_space "int nbytes"
+.Ft "int"
+.Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
+.Ft "int"
+.Fn inet6_option_append "struct cmsghdr *cmsg" "const u_int8_t *typep" "int multx" "int plusy"
+.Ft "u_int8_t *"
+.Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy";
+.Ft "int"
+.Fn inet6_option_next "const struct cmsghdr *cmsg" "u_int8_t **tptrp"
+.Ft "int"
+.Fn inet6_option_find "const struct cmsghdr *cmsg" "u_int8_t **tptrp" "int type"
+.\"
+.Sh DESCRIPTION
+.\"
+Building and parsing the Hop-by-Hop and Destination options is
+complicated due to alignment constranints, padding and
+ancillary data manipulation.
+RFC2292 defines a set of functions to help the application.
+The function prototypes for
+these functions are all in the
+.Aq Li netinet/in.h
+header.
+.\"
+.Ss inet6_option_space
+.Fn inet6_option_space
+returns the number of bytes required to hold an option when it is stored as
+ancillary data, including the
+.Li cmsghdr
+structure at the beginning,
+and any padding at the end
+.Po
+to make its size a multiple of 8 bytes
+.Pc .
+The argument is the size of the structure defining the option,
+which must include any pad bytes at the beginning
+.Po
+the value
+.Li y
+in the alignment term
+.Dq Li xn + y
+.Pc ,
+the type byte, the length byte, and the option data.
+.Pp
+Note: If multiple options are stored in a single ancillary data
+object, which is the recommended technique, this function
+overestimates the amount of space required by the size of
+.Li N-1
+.Li cmsghdr
+structures,
+where
+.Li N
+is the number of options to be stored in the object.
+This is of little consequence, since it is assumed that most
+Hop-by-Hop option headers and Destination option headers carry only
+one option
+.Pq appendix B of [RFC-2460] .
+.\"
+.Ss inet6_option_init
+.Fn inet6_option_init
+is called once per ancillary data object that will
+contain either Hop-by-Hop or Destination options.
+It returns
+.Li 0
+on success or
+.Li -1
+on an error.
+.Pp
+.Fa bp
+is a pointer to previously allocated space that will contain the
+ancillary data object.
+It must be large enough to contain all the
+individual options to be added by later calls to
+.Fn inet6_option_append
+and
+.Fn inet6_option_alloc .
+.Pp
+.Fa cmsgp
+is a pointer to a pointer to a
+.Li cmsghdr
+structure.
+.Fa *cmsgp
+is initialized by this function to point to the
+.Li cmsghdr
+structure constructed by this function in the buffer pointed to by
+.Fa bp .
+.Pp
+.Fa type
+is either
+.Dv IPV6_HOPOPTS
+or
+.Dv IPV6_DSTOPTS .
+This
+.Fa type
+is stored in the
+.Li cmsg_type
+member of the
+.Li cmsghdr
+structure pointed to by
+.Fa *cmsgp .
+.\"
+.Ss inet6_option_append
+This function appends a Hop-by-Hop option or a Destination option
+into an ancillary data object that has been initialized by
+.Fn inet6_option_init .
+This function returns
+.Li 0
+if it succeeds or
+.Li -1
+on an error.
+.Pp
+.Fa cmsg
+is a pointer to the
+.Li cmsghdr
+structure that must have been
+initialized by
+.Fn inet6_option_init .
+.Pp
+.Fa typep
+is a pointer to the 8-bit option type.
+It is assumed that this
+field is immediately followed by the 8-bit option data length field,
+which is then followed immediately by the option data.
+The caller
+initializes these three fields
+.Pq the type-length-value, or TLV
+before calling this function.
+.Pp
+The option type must have a value from
+.Li 2
+to
+.Li 255 , inclusive.
+.Po
+.Li 0
+and
+.Li 1
+are reserved for the
+.Li Pad1
+and
+.Li PadN
+options, respectively.
+.Pc
+.Pp
+The option data length must have a value between
+.Li 0
+and
+.Li 255 ,
+inclusive, and is the length of the option data that follows.
+.Pp
+.Fa multx
+is the value
+.Li x
+in the alignment term
+.Dq Li xn + y .
+It must have a value of
+.Li 1 ,
+.Li 2 ,
+.Li 4 ,
+or
+.Li 8 .
+.Pp
+.Fa plusy
+is the value
+.Li y
+in the alignment term
+.Dq Li xn + y .
+It must have a value between
+.Li 0
+and
+.Li 7 ,
+inclusive.
+.\"
+.Ss inet6_option_alloc
+This function appends a Hop-by-Hop option or a Destination option
+into an ancillary data object that has been initialized by
+.Fn inet6_option_init .
+This function returns a pointer to the 8-bit
+option type field that starts the option on success, or
+.Dv NULL
+on an error.
+.Pp
+The difference between this function and
+.Fn inet6_option_append
+is that the latter copies the contents of a previously built option into
+the ancillary data object while the current function returns a
+pointer to the space in the data object where the option's TLV must
+then be built by the caller.
+.Pp
+.Fa cmsg
+is a pointer to the
+.Li cmsghdr
+structure that must have been
+initialized by
+.Fn inet6_option_init .
+.Pp
+.Fa datalen
+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.
+.Po
+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.
+.Pc
+.Pp
+.Fa multx
+is the value
+.Li x
+in the alignment term
+.Dq Li xn + y .
+It must have a value of
+.Li 1 ,
+.Li 2 ,
+.Li 4 ,
+or
+.Li 8 .
+.Pp
+.Fa plusy
+is the value
+.Li y
+in the alignment term
+.Dq Li xn + y .
+It must have a value between
+.Li 0
+and
+.Li 7 ,
+inclusive.
+.\"
+.Ss inet6_option_next
+This function processes the next Hop-by-Hop option or Destination
+option in an ancillary data object.
+If another option remains to be
+processed, the return value of the function is
+.Li 0
+and
+.Fa *tptrp
+points to
+the 8-bit option type field
+.Po
+which is followed by the 8-bit option
+data length, followed by the option data
+.Pc .
+If no more options remain
+to be processed, the return value is
+.Li -1
+and
+.Fa *tptrp
+is
+.Dv NULL .
+If an error occurs, the return value is
+.Li -1
+and
+.Fa *tptrp
+is not
+.Dv NULL .
+.Pp
+.Fa cmsg
+is a pointer to
+.Li cmsghdr
+structure of which
+.Li cmsg_level
+equals
+.Dv IPPROTO_IPV6
+and
+.Li cmsg_type
+equals either
+.Dv IPV6_HOPOPTS
+or
+.Dv IPV6_DSTOPTS .
+.Pp
+.Fa tptrp
+is a pointer to a pointer to an 8-bit byte and
+.Fa *tptrp
+is used
+by the function to remember its place in the ancillary data object
+each time the function is called.
+The first time this function is
+called for a given ancillary data object,
+.Fa *tptrp
+must be set to
+.Dv NULL .
+.Pp 
+Each time this function returns success,
+.Fa *tptrp
+points to the 8-bit
+option type field for the next option to be processed.
+.\"
+.Ss inet6_option_find
+This function is similar to the previously described
+.Fn inet6_option_next
+function, except this function lets the caller
+specify the option type to be searched for, instead of always
+returning the next option in the ancillary data object.
+.Fa cmsg
+is a
+pointer to
+.Li cmsghdr
+structure of which
+.Li cmsg_level
+equals
+.Dv IPPROTO_IPV6
+and
+.Li cmsg_type
+equals either
+.Dv IPV6_HOPOPTS
+or
+.Dv IPV6_DSTOPTS .
+.Pp
+.Fa tptrp
+is a pointer to a pointer to an 8-bit byte and
+.Fa *tptrp
+is used
+by the function to remember its place in the ancillary data object
+each time the function is called.
+The first time this function is
+called for a given ancillary data object,
+.Fa *tptrp
+must be set to
+.Dv NULL .
+.Pa
+This function starts searching for an option of the specified type
+beginning after the value of
+.Fa *tptrp .
+If an option of the specified
+type is located, this function returns
+.Li 0
+and
+.Fa *tptrp
+points to the 8-
+bit option type field for the option of the specified type.
+If an
+option of the specified type is not located, the return value is
+.Li -1
+and
+.Fa *tptrp
+is
+.Dv NULL .
+If an error occurs, the return value is
+.Li -1
+and
+.Fa *tptrp
+is not
+.Dv NULL .
+.\"
+.Sh DIAGNOSTICS
+.Fn inet6_option_init
+and
+.Fn inet6_option_append
+return
+.Li 0
+on success or
+.Li -1
+on an error.
+.Pp
+.Fn inet6_option_alloc
+returns
+.Dv NULL on an error.
+.Pp
+On errors,
+.Fn inet6_option_next
+and
+.Fn inet6_option_find
+return
+.Li -1
+setting
+.Fa *tptrp
+to non 
+.Dv NULL
+value.
+.\"
+.Sh 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
+.Pq RFC2292 .
+.\"
+.Sh BUGS
+The text was shamelessly copied from RFC2292.
diff --git a/lib/libc/net/inet6_rthdr_space.3 b/lib/libc/net/inet6_rthdr_space.3
new file mode 100644
index 0000000..90bd88d
--- /dev/null
+++ b/lib/libc/net/inet6_rthdr_space.3
@@ -0,0 +1,326 @@
+.\" Copyright (c) 1983, 1987, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     $Id: inet6_rthdr_space.3,v 1.5 2000/02/05 13:19:07 jinmei Exp $
+.\" $FreeBSD$
+.\"
+.Dd December 10, 1999
+.Dt INET6_OPTION_SPACE 3
+.Os KAME
+.\"
+.Sh NAME
+.Nm inet6_rthdr_space ,
+.Nm inet6_rthdr_init ,
+.Nm inet6_rthdr_add ,
+.Nm inet6_rthdr_lasthop ,
+.Nm inet6_rthdr_reversoe ,
+.Nm inet6_rthdr_segments ,
+.Nm inet6_rthdr_getaddr ,
+.Nm inet6_rthdr_getflags
+.Nd IPv6 Routing Header Options manipulation
+.\"
+.Sh SYNOPSIS
+.Fd #include <netinet/in.h>
+.Ft size_t
+.Fn inet6_rthdr_space "int type" "int segments"
+.Ft "struct cmsghdr *"
+.Fn inet6_rthdr_init "void *bp" "int type"
+.Ft int
+.Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags"
+.Ft int
+.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags"
+.Ft int
+.Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out"
+.Ft int
+.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg"
+.Ft "struct in6_addr *"
+.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index"
+.Ft int
+.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index"
+.\"
+.Sh DESCRIPTION
+RFC2292 IPv6 advanced API defines eight
+functions that the application calls to build and examine a Routing
+header.  Four functions build a Routing header:
+.Bl -hang
+.It Fn inet6_rthdr_space
+return #bytes required for ancillary data
+.It Fn inet6_rthdr_init
+initialize ancillary data for Routing header
+.It Fn inet6_rthdr_add
+add IPv6 address & flags to Routing header
+.It Fn inet6_rthdr_lasthop
+specify the flags for the final hop
+.El
+.Pp
+Four functions deal with a returned Routing header:
+.Bl -hang
+.It Fn inet6_rthdr_reverse
+reverse a Routing header
+.It Fn inet6_rthdr_segments
+return #segments in a Routing header
+.It Fn inet6_rthdr_getaddr
+fetch one address from a Routing header
+.It Fn inet6_rthdr_getflags
+fetch one flag from a Routing header
+.El
+.Pp
+The function prototypes for these functions are all in the
+.Aq Li netinet/in.h
+header.
+.\"
+.Ss inet6_rthdr_space
+This function returns the number of bytes required to hold a Routing
+header of the specified
+.Fa type
+containing the specified number of
+.Fa segments
+.Pq addresses .
+For an IPv6 Type 0 Routing header, the number
+of segments must be between 1 and 23, inclusive.  The return value
+includes the size of the cmsghdr structure that precedes the Routing
+header, and any required padding.
+.Pp
+If the return value is 0, then either the type of the Routing header
+is not supported by this implementation or the number of segments is
+invalid for this type of Routing header.
+.Pp
+Note: This function returns the size but does not allocate the space
+required for the ancillary data.
+This allows an application to
+allocate a larger buffer, if other ancillary data objects are
+desired, since all the ancillary data objects must be specified to
+.Xr sendmsg 2
+as a single
+.Li msg_control
+buffer.
+.\"
+.Ss inet6_rthdr_init
+This function initializes the buffer pointed to by
+.Fa bp
+to contain a
+.Li cmsghdr
+structure followed by a Routing header of the specified
+.Fa type .
+The
+.Li cmsg_len
+member of the
+.Li cmsghdr
+structure is initialized to the
+size of the structure plus the amount of space required by the
+Routing header.
+The
+.Li cmsg_level
+and
+.Li cmsg_type
+members are also initialized as required.
+.Pp
+The caller must allocate the buffer and its size can be determined by
+calling
+.Fn inet6_rthdr_space .
+.Pp
+Upon success the return value is the pointer to the
+.Li cmsghdr
+structure, and this is then used as the first argument to the next
+two functions.
+Upon an error the return value is
+.Dv NULL .
+.\"
+.Ss inet6_rthdr_add
+This function adds the address pointed to by
+.Fa addr
+to the end of the
+Routing header being constructed and sets the type of this hop to the
+value of
+.Fa flags .
+For an IPv6 Type 0 Routing header,
+.Fa flags
+must be
+either
+.Dv IPV6_RTHDR_LOOSE
+or
+.Dv IPV6_RTHDR_STRICT .
+.Pp
+If successful, the
+.Li cmsg_len
+member of the
+.Li cmsghdr
+structure is
+updated to account for the new address in the Routing header and the
+return value of the function is 0.
+Upon an error the return value of
+the function is -1.
+.\"
+.Ss inet6_rthdr_lasthop
+This function specifies the Strict/Loose flag for the final hop of a
+Routing header.
+For an IPv6 Type 0 Routing header,
+.Fa flags
+must be either
+.Dv IPV6_RTHDR_LOOSE
+or
+.Dv IPV6_RTHDR_STRICT .
+.Pp
+The return value of the function is 0 upon success, or -1 upon an error.
+.Pp
+Notice that a Routing header specifying
+.Li N
+intermediate nodes requires
+.Li N+1
+Strict/Loose flags.
+This requires
+.Li N
+calls to
+.Fn inet6_rthdr_add
+followed by one call to
+.Fn inet6_rthdr_lasthop .
+.\"
+.Ss inet6_rthdr_reverse
+This function is not yet implemented.
+When implemented, this should behave as follows.
+.Pp
+This function takes a Routing header that was received as ancillary
+data
+.Po
+pointed to by the first argument,
+.Fa in
+.Pc
+and writes a new Routing
+header that sends datagrams along the reverse of that route.
+Both
+arguments are allowed to point to the same buffer
+.Pq that is, the reversal can occur in place .
+.Pp
+The return value of the function is 0 on success, or -1 upon an
+error.
+.\"
+.Ss inet6_rthdr_segments
+This function returns the number of segments
+.Pq addresses
+contained in
+the Routing header described by
+.Fa cmsg .
+On success the return value is
+between 1 and 23, inclusive.
+The return value of the function is -1 upon an error.
+.\"
+.Ss inet6_rthdr_getaddr
+This function returns a pointer to the IPv6 address specified by
+.Fa index
+.Po
+which must have a value between 1 and the value returned by
+.Fn inet6_rthdr_segments
+.Pc
+in the Routing header described by
+.Fa cmsg .
+An
+application should first call
+.Fn inet6_rthdr_segments
+to obtain the number of segments in the Routing header.
+.Pp
+Upon an error the return value of the function is
+.Dv NULL .
+.\"
+.Ss inet6_rthdr_getflags
+This function returns the flags value specified by
+.Fa index
+.Po
+which must
+have a value between 0 and the value returned by
+.Fn inet6_rthdr_segments
+.Pc
+in the Routing header described by
+.Fa cmsg .
+For an IPv6 Type 0 Routing header the return value will be either
+.Dv IPV6_RTHDR_LOOSE
+or
+.Dv IPV6_RTHDR_STRICT .
+.Pp
+Upon an error the return value of the function is -1.
+.Pp
+Note: Addresses are indexed starting at 1, and flags starting at 0,
+to maintain consistency with the terminology and figures in RFC2460.
+.\"
+.Sh DIAGNOSTICS
+.Fn inet6_rthdr_space
+returns 0 on errors.
+.Pp
+.Fn inet6_rthdr_add ,
+.Fn inet6_rthdr_lasthop
+and
+.Fn inet6_rthdr_reverse
+return 0 on success, and returns -1 on error.
+.Pp
+.Fn inet6_rthdr_init
+and
+.Fn inet6_rthdr_getaddr
+return
+.Dv NULL
+on error.
+.Pp
+.Fn inet6_rthdr_segments
+and
+.Fn inet6_rthdr_getflags
+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 STANDARDS
+The functions
+are documented in
+.Dq Advanced Sockets API for IPv6
+.Pq RFC2292 .
+.\"
+.Sh BUGS
+The text was shamelessly copied from RFC2292.
+.Pp
+.Fn inet6_rthdr_reverse
+is not implemented yet.