1 files changed, 254 insertions, 0 deletions
diff --git a/lib/libc/net/inet6_rth_space.3 b/lib/libc/net/inet6_rth_space.3
new file mode 100644
index 000000000000..1289b11b3eef
--- /dev/null
+++ b/lib/libc/net/inet6_rth_space.3
@@ -0,0 +1,254 @@
+.\"	$KAME: kame/kame/kame/libinet6/inet6_rth_space.3,v 1.4 2002/10/17 14:13:48 jinmei Exp $
+.\"	$FreeBSD$
+.\"
+.\" Copyright (C) 2000 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd February 5, 2000
+.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 defines six
+functions that the application calls to build and examine a Routing
+header, and the ability to use sticky options or ancillary data to
+communicate this information between the application and the kernel
+using the IPV6_RTHDR option.
+.Pp
+Three functions build a Routing header:
+.Bl -hang
+.It Fn inet6_rth_space
+returns #bytes required for Routing header
+.It Fn inet6_rth_init
+initializes buffer data for Routing header
+.It Fn inet6_rth_add
+adds one IPv6 address to the Routing header
+.El
+.Pp
+Three functions deal with a returned Routing header:
+.Bl -hang
+.It Fn inet6_rth_reverse
+reverses a Routing header
+.It Fn inet6_rth_segments
+returns #segments in a Routing header
+.It Fn inet6_rth_getaddr
+fetches one address from a Routing header
+.El
+.Pp
+The function prototypes for these functions are defined as a result
+of including the
+.Aq Li netinet/in.h
+header.
+.\"
+.Ss inet6_rth_space
+.Fn inet6_rth_space
+returns the number of bytes required to hold a Routing
+header of the specified type containing the specified number of
+.Li segments
+.Po addresses.
+.Pc
+For an IPv6 Type 0 Routing header, the number
+of
+.Li segments
+must be between 0 and 127, inclusive.
+The return value is just the space for the Routing header.
+When the application uses
+ancillary data it must pass the returned length to
+.Fn CMSG_LEN
+to determine how much memory is needed for the ancillary data object
+.Po
+including the cmsghdr structure.
+.Pc
+.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
+.Fn sendmsg
+as a single msg_control buffer.
+.Ss inet6_rth_init
+.Fn inet6_rth_init
+initializes the buffer pointed to by
+.Li bp
+to contain a
+Routing header of the specified type and sets ip6r_len based on the
+.Li segments
+parameter.
+.Li bp_len
+is only used to verify that the buffer is
+large enough.
+The ip6r_segleft field is set to zero;
+.Fn inet6_rth_add
+will increment it.
+.Pp
+When the application uses ancillary data the application must
+initialize any cmsghdr fields.
+.Pp
+The caller must allocate the buffer and its size can be determined by
+calling
+.Fn inet6_rth_space .
+.Pp
+Upon success the return value is the pointer to the buffer
+.Li bp ,
+and this is then used as the first argument to the next two functions.
+Upon an error the return value is NULL.
+.\"
+.Ss inet6_rth_add
+.Fn inet6_rth_add
+adds the IPv6 address pointed to by
+.Li addr
+to the end of the Routing header being constructed.
+.Pp
+If successful, the segleft member of the Routing Header 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_rth_reverse
+.Fn inet6_rth_reverse
+takes a Routing header extension header
+.Po
+pointed to by the first argument
+.Li 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
+.Po
+that is, the reversal can occur in place.
+.Pc
+.Pp
+The return value of the function is 0 on success, or -1 upon an error.
+.\"
+.Ss inet6_rth_segments
+.Fn inet6_rth_segments
+returns the number of segments
+.Po
+addresses
+.Pc
+contained in the Routing header described by
+.Li bp .
+On success the return value is
+zero or greater.
+The return value of the function is -1 upon an error.
+.\"
+.Ss inet6_rth_getaddr
+.Fn inet6_rth_getaddr
+returns a pointer to the IPv6 address specified by
+.Li index
+.Po
+which must have a value between 0 and one less than the value
+returned by
+.Fn inet6_rth_segments
+.Pc
+in the Routing header described by
+.Li bp .
+An application should first call
+.Fn inet6_rth_segments
+to obtain the number of segments in the Routing header.
+.Pp
+Upon an error the return value of the function is NULL.
+.\"
+.Sh DIAGNOSTICS
+.Fn inet6_rth_space
+and
+.FN inet6_rth_getaddr
+return 0 on errors.
+.Pp
+.Fn inet6_rthdr_init
+returns
+.Dv NULL
+on error.
+.Fn inet6_rth_add
+and
+.Fn inet6_rth_reverse
+return0 on success, or -1 upon an error.
+.\"
+.Sh EXAMPLES
+draft-ietf-ipngwg-rfc2292bis-08.txt
+gives comprehensive examples in Section 22.
+.Pp
+KAME also provides examples in the advapitest directry of its kit.
+.\"
+.Sh SEE ALSO
+.Rs
+.%A W. Stevens
+.%A M. Thomas
+.%A E. Nordmark
+.%A E. Jinmei
+.%T "Advanced Sockets API for IPv6"
+.%N draft-ietf-ipngwg-rfc2292bis-08
+.%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 draft-ietf-ipngwg-rfc2292bis-08.txt .
+.\"
+.Sh BUGS
+The text was shamelessly copied from internet-drafts for RFC2292bis.