Import from KAME. Advanced API related function descriptions.
Obtained from: KAME project
This commit is contained in:
shin
parent
6962f77cb9
commit
4a9ac000d9
@ -30,7 +30,8 @@ CFLAGS+=-DINET6
|
||||
MAN3+= addr2ascii.3 byteorder.3 ethers.3 getaddrinfo.3 gethostbyname.3 \
|
||||
getipnodebyname.3 \
|
||||
getnameinfo.3 getnetent.3 getprotoent.3 getservent.3 if_indextoname.3 \
|
||||
inet.3 linkaddr.3 rcmd.3 resolver.3
|
||||
inet.3 inet6_option_space.3 inet6_rthdr_space.3 linkaddr.3 \
|
||||
rcmd.3 resolver.3
|
||||
# not installed: iso_addr.3 ns.3
|
||||
|
||||
MLINKS+=addr2ascii.3 ascii2addr.3
|
||||
@ -56,6 +57,18 @@ MLINKS+=inet.3 addr.3 inet.3 inet_addr.3 inet.3 inet_aton.3 \
|
||||
inet.3 ntoa.3
|
||||
MLINKS+=if_indextoname.3 if_nametoindex.3 if_indextoname.3 if_nameindex.3 \
|
||||
if_indextoname.3 if_freenameindex.3
|
||||
MLINKS+=inet6_option_space.3 inet6_option_alloc.3 \
|
||||
inet6_option_space.3 inet6_option_append.3 \
|
||||
inet6_option_space.3 inet6_option_find.3 \
|
||||
inet6_option_space.3 inet6_option_init.3 \
|
||||
inet6_option_space.3 inet6_option_next.3 \
|
||||
inet6_rthdr_space.3 inet6_rthdr_add.3 \
|
||||
inet6_rthdr_space.3 inet6_rthdr_getaddr.3 \
|
||||
inet6_rthdr_space.3 inet6_rthdr_getflags.3 \
|
||||
inet6_rthdr_space.3 inet6_rthdr_init.3 \
|
||||
inet6_rthdr_space.3 inet6_rthdr_lasthop.3 \
|
||||
inet6_rthdr_space.3 inet6_rthdr_reverse.3 \
|
||||
inet6_rthdr_space.3 inet6_rthdr_segments.3
|
||||
MLINKS+=linkaddr.3 link_addr.3 linkaddr.3 link_ntoa.3
|
||||
#MLINKS+=ns.3 ns_addr.3 ns.3 ns_ntoa.3
|
||||
MLINKS+=rcmd.3 iruserok.3 rcmd.3 rresvport.3 rcmd.3 ruserok.3 \
|
||||
|
||||
450
lib/libc/net/inet6_option_space.3
Normal file
450
lib/libc/net/inet6_option_space.3
Normal file
@ -0,0 +1,450 @@
|
||||
.\" Copyright (c) 1983, 1987, 1991, 1993
|
||||
.\" The Regents of the University of California. 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. All advertising materials mentioning features or use of this software
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by the University of
|
||||
.\" California, Berkeley and its contributors.
|
||||
.\" 4. Neither the name of the University 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 REGENTS 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 REGENTS 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.
|
||||
.\"
|
||||
.\" $Id: inet6_option_space.3,v 1.4 2000/02/05 10:32:24 jinmei Exp $
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd December 10, 1999
|
||||
.Dt INET6_OPTION_SPACE 3
|
||||
.Os KAME
|
||||
.\"
|
||||
.Sh NAME
|
||||
.Nm inet6_option_space ,
|
||||
.Nm inet6_option_init ,
|
||||
.Nm inet6_option_append ,
|
||||
.Nm inet6_option_alloc ,
|
||||
.Nm inet6_option_next ,
|
||||
.Nm inet6_option_find
|
||||
.Nd IPv6 Hop-by-Hop and Destination Options manipulation
|
||||
.\"
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <netinet/in.h>
|
||||
.Ft "int"
|
||||
.Fn inet6_options_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
|
||||
.\"
|
||||
Building and parsing the Hop-by-Hop and Destination options is
|
||||
complicated due to alignment constranints, padding and
|
||||
ancillary data manipulation.
|
||||
RFC2292 defines a set of functions to help the application.
|
||||
The function prototypes for
|
||||
these functions are all in the
|
||||
.Aq Li netinet/in.h
|
||||
header.
|
||||
.\"
|
||||
.Ss inet6_option_space
|
||||
.Fn inet6_option_space
|
||||
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 padding at the end
|
||||
.Po
|
||||
to make its size a multiple of 8 bytes
|
||||
.Pc .
|
||||
The argument is the size of the structure defining the option,
|
||||
which must include any pad bytes at the beginning
|
||||
.Po
|
||||
the value
|
||||
.Li y
|
||||
in the alignment term
|
||||
.Dq Li xn + y
|
||||
.Pc ,
|
||||
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, this 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.
|
||||
This is of little consequence, since it is assumed that most
|
||||
Hop-by-Hop option headers and Destination option headers carry only
|
||||
one option
|
||||
.Pq appendix B of [RFC-2460] .
|
||||
.\"
|
||||
.Ss inet6_option_init
|
||||
.Fn inet6_option_init
|
||||
is called once per ancillary data object that will
|
||||
contain either Hop-by-Hop or Destination options.
|
||||
It returns
|
||||
.Li 0
|
||||
on success or
|
||||
.Li -1
|
||||
on an error.
|
||||
.Pp
|
||||
.Fa bp
|
||||
is a pointer to previously allocated space that will contain the
|
||||
ancillary data object.
|
||||
It must be large enough to contain all the
|
||||
individual options to be added by later calls to
|
||||
.Fn inet6_option_append
|
||||
and
|
||||
.Fn inet6_option_alloc .
|
||||
.Pp
|
||||
.Fa cmsgp
|
||||
is a pointer to a pointer to a
|
||||
.Li cmsghdr
|
||||
structure.
|
||||
.Fa *cmsgp
|
||||
is initialized by this function to point to the
|
||||
.Li cmsghdr
|
||||
structure constructed by this function in the buffer pointed to by
|
||||
.Fa bp .
|
||||
.Pp
|
||||
.Fa type
|
||||
is either
|
||||
.Dv IPV6_HOPOPTS
|
||||
or
|
||||
.Dv IPV6_DSTOPTS .
|
||||
This
|
||||
.Fa type
|
||||
is stored in the
|
||||
.Li cmsg_type
|
||||
member of the
|
||||
.Li cmsghdr
|
||||
structure pointed to by
|
||||
.Fa *cmsgp .
|
||||
.\"
|
||||
.Ss inet6_option_append
|
||||
This function appends a Hop-by-Hop option or a Destination option
|
||||
into an ancillary data object that has been initialized by
|
||||
.Fn inet6_option_init .
|
||||
This function returns
|
||||
.Li 0
|
||||
if it succeeds or
|
||||
.Li -1
|
||||
on an error.
|
||||
.Pp
|
||||
.Fa cmsg
|
||||
is a pointer to the
|
||||
.Li cmsghdr
|
||||
structure that must have been
|
||||
initialized by
|
||||
.Fn inet6_option_init .
|
||||
.Pp
|
||||
.Fa typep
|
||||
is a pointer to the 8-bit option type.
|
||||
It is assumed that this
|
||||
field is immediately followed by the 8-bit option data length field,
|
||||
which is then followed immediately by the option data.
|
||||
The caller
|
||||
initializes these three fields
|
||||
.Pq the type-length-value, or TLV
|
||||
before calling this function.
|
||||
.Pp
|
||||
The option type must have a value from
|
||||
.Li 2
|
||||
to
|
||||
.Li 255 , inclusive.
|
||||
.Po
|
||||
.Li 0
|
||||
and
|
||||
.Li 1
|
||||
are reserved for the
|
||||
.Li Pad1
|
||||
and
|
||||
.Li PadN
|
||||
options, respectively.
|
||||
.Pc
|
||||
.Pp
|
||||
The option data length must have a value between
|
||||
.Li 0
|
||||
and
|
||||
.Li 255 ,
|
||||
inclusive, and is the length of the option data that follows.
|
||||
.Pp
|
||||
.Fa multx
|
||||
is the value
|
||||
.Li x
|
||||
in the alignment term
|
||||
.Dq Li xn + y .
|
||||
It must have a value of
|
||||
.Li 1 ,
|
||||
.Li 2 ,
|
||||
.Li 4 ,
|
||||
or
|
||||
.Li 8 .
|
||||
.Pp
|
||||
.Fa plusy
|
||||
is the value
|
||||
.Li y
|
||||
in the alignment term
|
||||
.Dq Li xn + y .
|
||||
It must have a value between
|
||||
.Li 0
|
||||
and
|
||||
.Li 7 ,
|
||||
inclusive.
|
||||
.\"
|
||||
.Ss inet6_option_alloc
|
||||
This function appends a Hop-by-Hop option or a Destination option
|
||||
into an ancillary data object that has been initialized by
|
||||
.Fn inet6_option_init .
|
||||
This function returns a pointer to the 8-bit
|
||||
option type field that starts the option on success, or
|
||||
.Dv NULL
|
||||
on an error.
|
||||
.Pp
|
||||
The difference between this function and
|
||||
.Fn inet6_option_append
|
||||
is that the latter copies the contents of a previously built option into
|
||||
the ancillary data object while the current function returns a
|
||||
pointer to the space in the data object where the option's TLV must
|
||||
then be built by the caller.
|
||||
.Pp
|
||||
.Fa cmsg
|
||||
is a pointer to the
|
||||
.Li cmsghdr
|
||||
structure that must have been
|
||||
initialized by
|
||||
.Fn inet6_option_init .
|
||||
.Pp
|
||||
.Fa datalen
|
||||
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.
|
||||
.Po
|
||||
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.
|
||||
.Pc
|
||||
.Pp
|
||||
.Fa multx
|
||||
is the value
|
||||
.Li x
|
||||
in the alignment term
|
||||
.Dq Li xn + y .
|
||||
It must have a value of
|
||||
.Li 1 ,
|
||||
.Li 2 ,
|
||||
.Li 4 ,
|
||||
or
|
||||
.Li 8 .
|
||||
.Pp
|
||||
.Fa plusy
|
||||
is the value
|
||||
.Li y
|
||||
in the alignment term
|
||||
.Dq Li xn + y .
|
||||
It must have a value between
|
||||
.Li 0
|
||||
and
|
||||
.Li 7 ,
|
||||
inclusive.
|
||||
.\"
|
||||
.Ss inet6_option_next
|
||||
This function processes the next Hop-by-Hop option or Destination
|
||||
option in an ancillary data object.
|
||||
If another option remains to be
|
||||
processed, the return value of the function is
|
||||
.Li 0
|
||||
and
|
||||
.Fa *tptrp
|
||||
points to
|
||||
the 8-bit option type field
|
||||
.Po
|
||||
which is followed by the 8-bit option
|
||||
data length, followed by the option data
|
||||
.Pc .
|
||||
If no more options remain
|
||||
to be processed, the return value is
|
||||
.Li -1
|
||||
and
|
||||
.Fa *tptrp
|
||||
is
|
||||
.Dv NULL .
|
||||
If an error occurs, the return value is
|
||||
.Li -1
|
||||
and
|
||||
.Fa *tptrp
|
||||
is not
|
||||
.Dv NULL .
|
||||
.Pp
|
||||
.Fa cmsg
|
||||
is a pointer to
|
||||
.Li cmsghdr
|
||||
structure of which
|
||||
.Li cmsg_level
|
||||
equals
|
||||
.Dv IPPROTO_IPV6
|
||||
and
|
||||
.Li cmsg_type
|
||||
equals either
|
||||
.Dv IPV6_HOPOPTS
|
||||
or
|
||||
.Dv IPV6_DSTOPTS .
|
||||
.Pp
|
||||
.Fa tptrp
|
||||
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.
|
||||
The first time this function is
|
||||
called for a given ancillary data object,
|
||||
.Fa *tptrp
|
||||
must be set to
|
||||
.Dv NULL .
|
||||
.Pp
|
||||
Each time this function returns success,
|
||||
.Fa *tptrp
|
||||
points to the 8-bit
|
||||
option type field for the next option to be processed.
|
||||
.\"
|
||||
.Ss inet6_option_find
|
||||
This function is similar to the previously described
|
||||
.Fn inet6_option_next
|
||||
function, except this function lets the caller
|
||||
specify the option type to be searched for, instead of always
|
||||
returning the next option in the ancillary data object.
|
||||
.Fa cmsg
|
||||
is a
|
||||
pointer to
|
||||
.Li cmsghdr
|
||||
structure of which
|
||||
.Li cmsg_level
|
||||
equals
|
||||
.Dv IPPROTO_IPV6
|
||||
and
|
||||
.Li cmsg_type
|
||||
equals either
|
||||
.Dv IPV6_HOPOPTS
|
||||
or
|
||||
.Dv IPV6_DSTOPTS .
|
||||
.Pp
|
||||
.Fa tptrp
|
||||
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.
|
||||
The first time this function is
|
||||
called for a given ancillary data object,
|
||||
.Fa *tptrp
|
||||
must be set to
|
||||
.Dv NULL .
|
||||
.Pa
|
||||
This function starts searching for an option of the specified type
|
||||
beginning after the value of
|
||||
.Fa *tptrp .
|
||||
If an option of the specified
|
||||
type is located, this function returns
|
||||
.Li 0
|
||||
and
|
||||
.Fa *tptrp
|
||||
points to the 8-
|
||||
bit option type field for the option of the specified type.
|
||||
If an
|
||||
option of the specified type is not located, the return value is
|
||||
.Li -1
|
||||
and
|
||||
.Fa *tptrp
|
||||
is
|
||||
.Dv NULL .
|
||||
If an error occurs, the return value is
|
||||
.Li -1
|
||||
and
|
||||
.Fa *tptrp
|
||||
is not
|
||||
.Dv NULL .
|
||||
.\"
|
||||
.Sh DIAGNOSTICS
|
||||
.Fn inet6_option_init
|
||||
and
|
||||
.Fn inet6_option_append
|
||||
return
|
||||
.Li 0
|
||||
on success or
|
||||
.Li -1
|
||||
on an error.
|
||||
.Pp
|
||||
.Fn inet6_option_alloc
|
||||
returns
|
||||
.Dv NULL on an error.
|
||||
.Pp
|
||||
On errors,
|
||||
.Fn inet6_option_next
|
||||
and
|
||||
.Fn inet6_option_find
|
||||
return
|
||||
.Li -1
|
||||
setting
|
||||
.Fa *tptrp
|
||||
to non
|
||||
.Dv NULL
|
||||
value.
|
||||
.\"
|
||||
.Sh EXAMPLES
|
||||
RFC2292 gives comprehensive examples in chapter 6.
|
||||
.\"
|
||||
.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 STANDARDS
|
||||
The functions
|
||||
are documented in
|
||||
.Dq Advanced Sockets API for IPv6
|
||||
.Pq RFC2292 .
|
||||
.\"
|
||||
.Sh BUGS
|
||||
The text was shamelessly copied from RFC2292.
|
||||
326
lib/libc/net/inet6_rthdr_space.3
Normal file
326
lib/libc/net/inet6_rthdr_space.3
Normal file
@ -0,0 +1,326 @@
|
||||
.\" Copyright (c) 1983, 1987, 1991, 1993
|
||||
.\" The Regents of the University of California. 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. All advertising materials mentioning features or use of this software
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by the University of
|
||||
.\" California, Berkeley and its contributors.
|
||||
.\" 4. Neither the name of the University 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 REGENTS 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 REGENTS 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.
|
||||
.\"
|
||||
.\" $Id: inet6_rthdr_space.3,v 1.5 2000/02/05 13:19:07 jinmei Exp $
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd December 10, 1999
|
||||
.Dt INET6_OPTION_SPACE 3
|
||||
.Os KAME
|
||||
.\"
|
||||
.Sh NAME
|
||||
.Nm inet6_rthdr_space ,
|
||||
.Nm inet6_rthdr_init ,
|
||||
.Nm inet6_rthdr_add ,
|
||||
.Nm inet6_rthdr_lasthop ,
|
||||
.Nm inet6_rthdr_reversoe ,
|
||||
.Nm inet6_rthdr_segments ,
|
||||
.Nm inet6_rthdr_getaddr ,
|
||||
.Nm inet6_rthdr_getflags
|
||||
.Nd IPv6 Routing Header Options manipulation
|
||||
.\"
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <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
|
||||
RFC2292 IPv6 advanced API defines eight
|
||||
functions that the application calls to build and examine a Routing
|
||||
header. Four functions build a Routing header:
|
||||
.Bl -hang
|
||||
.It Fn inet6_rthdr_space
|
||||
return #bytes required for ancillary data
|
||||
.It Fn inet6_rthdr_init
|
||||
initialize ancillary data for Routing header
|
||||
.It Fn inet6_rthdr_add
|
||||
add IPv6 address & flags to Routing header
|
||||
.It Fn inet6_rthdr_lasthop
|
||||
specify the flags for the final hop
|
||||
.El
|
||||
.Pp
|
||||
Four functions deal with a returned Routing header:
|
||||
.Bl -hang
|
||||
.It Fn inet6_rthdr_reverse
|
||||
reverse a Routing header
|
||||
.It Fn inet6_rthdr_segments
|
||||
return #segments in a Routing header
|
||||
.It Fn inet6_rthdr_getaddr
|
||||
fetch one address from a Routing header
|
||||
.It Fn inet6_rthdr_getflags
|
||||
fetch one flag from a Routing header
|
||||
.El
|
||||
.Pp
|
||||
The function prototypes for these functions are all in the
|
||||
.Aq Li netinet/in.h
|
||||
header.
|
||||
.\"
|
||||
.Ss inet6_rthdr_space
|
||||
This function returns the number of bytes required to hold a Routing
|
||||
header of the specified
|
||||
.Fa type
|
||||
containing the specified number of
|
||||
.Fa segments
|
||||
.Pq addresses .
|
||||
For an IPv6 Type 0 Routing header, the number
|
||||
of segments must be between 1 and 23, inclusive. The return value
|
||||
includes the size of the cmsghdr structure that precedes the Routing
|
||||
header, and any required padding.
|
||||
.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
|
||||
.Xr sendmsg 2
|
||||
as a single
|
||||
.Li msg_control
|
||||
buffer.
|
||||
.\"
|
||||
.Ss inet6_rthdr_init
|
||||
This function initializes the buffer pointed to by
|
||||
.Fa bp
|
||||
to contain a
|
||||
.Li cmsghdr
|
||||
structure followed by a Routing header of the specified
|
||||
.Fa type .
|
||||
The
|
||||
.Li cmsg_len
|
||||
member of the
|
||||
.Li cmsghdr
|
||||
structure is initialized to the
|
||||
size of the structure plus the amount of space required by the
|
||||
Routing header.
|
||||
The
|
||||
.Li cmsg_level
|
||||
and
|
||||
.Li cmsg_type
|
||||
members are also initialized as required.
|
||||
.Pp
|
||||
The caller must allocate the buffer and its size can be determined by
|
||||
calling
|
||||
.Fn inet6_rthdr_space .
|
||||
.Pp
|
||||
Upon success the return value is the pointer to the
|
||||
.Li cmsghdr
|
||||
structure, and this is then used as the first argument to the next
|
||||
two functions.
|
||||
Upon an error the return value is
|
||||
.Dv NULL .
|
||||
.\"
|
||||
.Ss inet6_rthdr_add
|
||||
This function adds the address pointed to by
|
||||
.Fa addr
|
||||
to the end of the
|
||||
Routing header being constructed and sets the type of this hop to the
|
||||
value of
|
||||
.Fa flags .
|
||||
For an IPv6 Type 0 Routing header,
|
||||
.Fa flags
|
||||
must be
|
||||
either
|
||||
.Dv IPV6_RTHDR_LOOSE
|
||||
or
|
||||
.Dv IPV6_RTHDR_STRICT .
|
||||
.Pp
|
||||
If successful, the
|
||||
.Li cmsg_len
|
||||
member of the
|
||||
.Li cmsghdr
|
||||
structure 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_rthdr_lasthop
|
||||
This function specifies the Strict/Loose flag for the final hop of a
|
||||
Routing header.
|
||||
For an IPv6 Type 0 Routing header,
|
||||
.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, or -1 upon an error.
|
||||
.Pp
|
||||
Notice that a Routing header specifying
|
||||
.Li N
|
||||
intermediate nodes requires
|
||||
.Li N+1
|
||||
Strict/Loose flags.
|
||||
This requires
|
||||
.Li N
|
||||
calls to
|
||||
.Fn inet6_rthdr_add
|
||||
followed by one call to
|
||||
.Fn inet6_rthdr_lasthop .
|
||||
.\"
|
||||
.Ss inet6_rthdr_reverse
|
||||
This function is not yet implemented.
|
||||
When implemented, this should behave as follows.
|
||||
.Pp
|
||||
This function takes a Routing header that was received as ancillary
|
||||
data
|
||||
.Po
|
||||
pointed to by the first argument,
|
||||
.Fa 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
|
||||
.Pq that is, the reversal can occur in place .
|
||||
.Pp
|
||||
The return value of the function is 0 on success, or -1 upon an
|
||||
error.
|
||||
.\"
|
||||
.Ss inet6_rthdr_segments
|
||||
This function returns the number of segments
|
||||
.Pq addresses
|
||||
contained in
|
||||
the Routing header described by
|
||||
.Fa cmsg .
|
||||
On success the return value is
|
||||
between 1 and 23, inclusive.
|
||||
The return value of the function is -1 upon an error.
|
||||
.\"
|
||||
.Ss inet6_rthdr_getaddr
|
||||
This function returns a pointer to the IPv6 address specified by
|
||||
.Fa index
|
||||
.Po
|
||||
which must have a value between 1 and the value returned by
|
||||
.Fn inet6_rthdr_segments
|
||||
.Pc
|
||||
in the Routing header described by
|
||||
.Fa cmsg .
|
||||
An
|
||||
application should first call
|
||||
.Fn inet6_rthdr_segments
|
||||
to obtain the number of segments in the Routing header.
|
||||
.Pp
|
||||
Upon an error the return value of the function is
|
||||
.Dv NULL .
|
||||
.\"
|
||||
.Ss inet6_rthdr_getflags
|
||||
This function returns the flags value specified by
|
||||
.Fa index
|
||||
.Po
|
||||
which must
|
||||
have a value between 0 and the value returned by
|
||||
.Fn inet6_rthdr_segments
|
||||
.Pc
|
||||
in the Routing header described by
|
||||
.Fa cmsg .
|
||||
For an IPv6 Type 0 Routing header the return value will be either
|
||||
.Dv IPV6_RTHDR_LOOSE
|
||||
or
|
||||
.Dv IPV6_RTHDR_STRICT .
|
||||
.Pp
|
||||
Upon an error the return value of the function is -1.
|
||||
.Pp
|
||||
Note: Addresses are indexed starting at 1, and flags starting at 0,
|
||||
to maintain consistency with the terminology and figures in RFC2460.
|
||||
.\"
|
||||
.Sh DIAGNOSTICS
|
||||
.Fn inet6_rthdr_space
|
||||
returns 0 on errors.
|
||||
.Pp
|
||||
.Fn inet6_rthdr_add ,
|
||||
.Fn inet6_rthdr_lasthop
|
||||
and
|
||||
.Fn inet6_rthdr_reverse
|
||||
return 0 on success, and returns -1 on error.
|
||||
.Pp
|
||||
.Fn inet6_rthdr_init
|
||||
and
|
||||
.Fn inet6_rthdr_getaddr
|
||||
return
|
||||
.Dv NULL
|
||||
on error.
|
||||
.Pp
|
||||
.Fn inet6_rthdr_segments
|
||||
and
|
||||
.Fn inet6_rthdr_getflags
|
||||
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 STANDARDS
|
||||
The functions
|
||||
are documented in
|
||||
.Dq Advanced Sockets API for IPv6
|
||||
.Pq RFC2292 .
|
||||
.\"
|
||||
.Sh BUGS
|
||||
The text was shamelessly copied from RFC2292.
|
||||
.Pp
|
||||
.Fn inet6_rthdr_reverse
|
||||
is not implemented yet.
|
||||
Loading…
Reference in New Issue
Block a user