6617cf5778
Reviewed by: Kame Project (including Itojun-san, Jinmei-san and Suzuki-san) Approved by: Robert Watson (robert at freebsd dot org) Obtained from: Kame Project and OpenBSD Replace manual pages that may have violated the IETF's Copyright. All come from the Kame tree. Several were from OpenBSD except for ip6.4, and the inet6* pages which were rewritten by me. All of the text is new and drawn from reading the code and documentation.
306 lines
8.1 KiB
Groff
306 lines
8.1 KiB
Groff
.\" $KAME: inet6_rthdr_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.\" 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 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.
|
|
.\"
|
|
.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
|