.\"	$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