1 files changed, 308 insertions, 0 deletions

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..7c00c42e42
--- /dev/null
+++ b/src/lib/libc/net/inet6_rthdr_space.3
@@ -0,0 +1,308 @@
+.\"     $OpenBSD: inet6_rthdr_space.3,v 1.17 2005/01/11 17:45:41 jaredy 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 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
+.Aq Pa 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
+.Vt 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
+argument 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 three 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,
+.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 RFC 2460.
+.\"
+.Sh EXAMPLES
+RFC 2292 gives comprehensive examples in chapter 8.
+.\"
+.Sh DIAGNOSTICS
+The
+.Fn inet6_rthdr_space
+function returns 0 when an error occurs.
+.Pp
+The
+.Fn inet6_rthdr_add
+and
+.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 SEE ALSO
+.Xr inet6 4 ,
+.Xr ip6 4
+.Rs
+.%A W. Stevens
+.%A M. Thomas
+.%T "Advanced Sockets API for IPv6"
+.%N RFC 2292
+.%D February 1998
+.Re
+.Rs
+.%A S. Deering
+.%A R. Hinden
+.%T "Internet Protocol, Version 6 (IPv6) Specification"
+.%N RFC 2460
+.%D December 1998
+.Re
+.\"
+.Sh HISTORY
+This implementation first appeared in the 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