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.
224 lines
6.9 KiB
Groff
224 lines
6.9 KiB
Groff
.\" $KAME: inet6_rth_space.3,v 1.7 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 24, 2004
|
|
.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, RFC 3542, defines the functions that an
|
|
application calls to build and examine IPv6 Routing headers.
|
|
Routing headers are used to perform source routing in IPv6 networks.
|
|
The RFC uses the word
|
|
.Dq segments
|
|
to describe addresses and that is the term used here as well.
|
|
All of the functions are defined in the
|
|
.In netinet/in.h
|
|
header file.
|
|
The functions described in this manual page all operate
|
|
on routing header structures which are defined in
|
|
.In netinet/ip6.h
|
|
but which should not need to be modified outside the use of this API.
|
|
The size and shape of the route header structures may change, so using
|
|
the APIs is a more portable, long term, solution.
|
|
.Pp
|
|
The functions in the API are split into two groups, those that build a
|
|
routing header and those that parse a received routing header.
|
|
We will describe the builder functions followed by the parser functions.
|
|
.Ss inet6_rth_space
|
|
The
|
|
.Fn inet6_rth_space
|
|
function returns the number of bytes required to hold a Routing Header
|
|
of the type, specified in the
|
|
.Fa type
|
|
argument and containing the number of addresses specified in the
|
|
.Fa segments
|
|
argumment.
|
|
When the type is
|
|
.Dv IPV6_RTHDR_TYPE_0
|
|
the number of segments must be from 0 through 127.
|
|
Routing headers of type
|
|
.Dv IPV6_RTHDR_TYPE_2
|
|
contain only one segment, and are only used with Mobile IPv6.
|
|
The return value from this function is the number of bytes required to
|
|
store the routing header.
|
|
If the value 0 is returned then either the
|
|
route header type was not recognized or another error occurred.
|
|
.Ss inet6_rth_init
|
|
The
|
|
.Fn inet6_rth_init
|
|
function initializes the pre-allocated buffer pointed to by
|
|
.Fa bp
|
|
to contain a routing header of the specified type The
|
|
.Fa bp_len
|
|
argument is used to verify that the buffer is large enough.
|
|
The caller must allocate the buffer pointed to by bp.
|
|
The necessary buffer size should be determined by calling
|
|
.Fn inet6_rth_space
|
|
described in the previous sections.
|
|
.Pp
|
|
The
|
|
.Fn inet6_rth_init
|
|
function returns a pointer to
|
|
.Fa bp
|
|
on success and
|
|
.Dv NULL
|
|
when there is an error.
|
|
.Ss inet6_rth_add
|
|
The
|
|
.Fn inet6_rth_add
|
|
function adds the IPv6 address pointed to by
|
|
.Fa addr
|
|
to the end of the routing header being constructed.
|
|
.Pp
|
|
A successful addition results in the function returning 0, otherwise
|
|
\-1 is returned.
|
|
.Ss inet6_rth_reverse
|
|
The
|
|
.Fn inet6_rth_reverse
|
|
function takes a routing header, pointed to by the
|
|
argument
|
|
.Fa in ,
|
|
and writes a new routing header into the argument pointed to by
|
|
.Fa out .
|
|
The routing header at that sends datagrams along the reverse of that
|
|
route.
|
|
Both arguments are allowed to point to the same buffer meaning
|
|
that the reversal can occur in place.
|
|
.Pp
|
|
The return value of the function is 0 on success, or \-1 when
|
|
there is an error.
|
|
.\"
|
|
.Pp
|
|
The next set of functions operate on a routing header that the
|
|
application wants to parse.
|
|
In the usual case such a routing header
|
|
is received from the network, although these functions can also be
|
|
used with routing headers that the application itself created.
|
|
.Ss inet6_rth_segments
|
|
The
|
|
.Fn inet6_rth_segments
|
|
function returns the number of segments contained in the
|
|
routing header pointed to by
|
|
.Fa bp .
|
|
The return value is the number of segments contained in the routing
|
|
header, or \-1 if an error occurred.
|
|
It is not an error for 0 to be
|
|
returned as a routing header may contain 0 segments.
|
|
.\"
|
|
.Ss inet6_rth_getaddr
|
|
The
|
|
.Fn inet6_rth_getaddr
|
|
function is used to retrieve a single address from a routing header.
|
|
The
|
|
.Fa index
|
|
is the location in the routing header from which the application wants
|
|
to retrieve an address.
|
|
The
|
|
.Fa index
|
|
parameter must have a value between 0 and one less than the number of
|
|
segments present in the routing header.
|
|
The
|
|
.Fn inet6_rth_segments
|
|
function, described in the last section, should be used to determine
|
|
the total number of segments in the routing header.
|
|
The
|
|
.Fn inet6_rth_getaddr
|
|
function returns a pointer to an IPv6 address on success or
|
|
.Dv NULL
|
|
when an error has occurred.
|
|
.\"
|
|
.Sh DIAGNOSTICS
|
|
The
|
|
.Fn inet6_rth_space
|
|
and
|
|
.Fn inet6_rth_getaddr
|
|
functions return 0 on errors.
|
|
.Pp
|
|
The
|
|
.Fn inet6_rthdr_init
|
|
function returns
|
|
.Dv NULL
|
|
on error.
|
|
The
|
|
.Fn inet6_rth_add
|
|
and
|
|
.Fn inet6_rth_reverse
|
|
functions return 0 on success, or \-1 upon an error.
|
|
.\"
|
|
.Sh EXAMPLES
|
|
RFC 3542 gives extensive examples in Section 21, Appendix B.
|
|
.Pp
|
|
KAME also provides examples in the advapitest directory of its kit.
|
|
.\"
|
|
.Sh SEE ALSO
|
|
.Rs
|
|
.%A W. Stevens
|
|
.%A M. Thomas
|
|
.%A E. Nordmark
|
|
.%A T. Jinmei
|
|
.%T "Advanced Sockets API for IPv6"
|
|
.%N RFC 3542
|
|
.%D May 2003
|
|
.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.
|