Update man pages to be in line with guidelines for IPv6 in FreeBSD.

FreeBSD currently implements the most up to date IPv6 APIs for
option and route header parsing.   This checkin marks the older APIs
as deprecated and points the reader to the newer pages.

Reviewed by: Jun-ichiro Itojun
Approved by: rwatson (mentor)

3 files changed, 17 insertions, 653 deletions

diff --git a/lib/libc/net/inet6_opt_init.3 b/lib/libc/net/inet6_opt_init.3
index b668792..ab0d017 100644
--- a/lib/libc/net/inet6_opt_init.3
+++ b/lib/libc/net/inet6_opt_init.3
@@ -65,13 +65,8 @@ 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.
+This man page describes the functions specified in
+IETF Draft RFC3542.
 These functions use the
 formatting rules specified in Appendix B in RFC2460, i.e., that the
 largest field is placed last in the option.
diff --git a/lib/libc/net/inet6_option_space.3 b/lib/libc/net/inet6_option_space.3
index c6bf1b5..bd172c2 100644
--- a/lib/libc/net/inet6_option_space.3
+++ b/lib/libc/net/inet6_option_space.3
@@ -28,7 +28,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd December 23, 2004
+.Dd January 24, 2005
 .Dt INET6_OPTION_SPACE 3
 .Os
 .\"
@@ -41,394 +41,13 @@
 .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.
-.\"
+The functions that were documented in this manual page are now
+deprecated in favor of those described in
+.Xr inet6_opt_init 3 .
+ Please refer to that manual page for information on how to manipulate
+IPv6 Hop-by-Hop and Destination options.
 .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.
+.Xr inet6_opt_init 3 ,
 .\"
-.Sh STANDARDS
-The functions are documented in
-.Dq Advanced Sockets API for IPv6
-(RFC2292).
 .\"
diff --git a/lib/libc/net/inet6_rthdr_space.3 b/lib/libc/net/inet6_rthdr_space.3
index bd49243..c579438 100644
--- a/lib/libc/net/inet6_rthdr_space.3
+++ b/lib/libc/net/inet6_rthdr_space.3
@@ -28,7 +28,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd December 27, 2004
+.Dd January 24, 2005
 .Dt INET6_RTHDR_SPACE 3
 .Os
 .\"
@@ -43,263 +43,13 @@
 .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.
+The RFC 2292 IPv6 Advanced API has been deprecated in favor of the
+newer, RFC 3542 APIs documented in
+.Xr inet6_rth_space 3 .
+On platforms that support it, currently only
+FreeBSD, please use the newer API to manipulate routing header
+options.
 .\"
 .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
+.Xr inet6_rth_space 3