add manpage for inet6_{option,rthdr}_*.
This commit is contained in:
itojun
parent
2e825f9c4e
commit
a57d497906
@ -1,4 +1,4 @@
|
|||||||
# $NetBSD: mi,v 1.172 1999/12/10 23:23:01 jlam Exp $
|
# $NetBSD: mi,v 1.173 1999/12/12 11:20:03 itojun Exp $
|
||||||
./sys
|
./sys
|
||||||
./usr/bin/ar
|
./usr/bin/ar
|
||||||
./usr/bin/as
|
./usr/bin/as
|
||||||
@ -3274,6 +3274,20 @@
|
|||||||
./usr/share/man/man3/ilogbf.3
|
./usr/share/man/man3/ilogbf.3
|
||||||
./usr/share/man/man3/index.3
|
./usr/share/man/man3/index.3
|
||||||
./usr/share/man/man3/inet.3
|
./usr/share/man/man3/inet.3
|
||||||
|
./usr/share/man/man3/inet6_option_alloc.3
|
||||||
|
./usr/share/man/man3/inet6_option_append.3
|
||||||
|
./usr/share/man/man3/inet6_option_find.3
|
||||||
|
./usr/share/man/man3/inet6_option_init.3
|
||||||
|
./usr/share/man/man3/inet6_option_next.3
|
||||||
|
./usr/share/man/man3/inet6_option_space.3
|
||||||
|
./usr/share/man/man3/inet6_rthdr_add.3
|
||||||
|
./usr/share/man/man3/inet6_rthdr_getaddr.3
|
||||||
|
./usr/share/man/man3/inet6_rthdr_getflags.3
|
||||||
|
./usr/share/man/man3/inet6_rthdr_init.3
|
||||||
|
./usr/share/man/man3/inet6_rthdr_lasthop.3
|
||||||
|
./usr/share/man/man3/inet6_rthdr_reverse.3
|
||||||
|
./usr/share/man/man3/inet6_rthdr_segments.3
|
||||||
|
./usr/share/man/man3/inet6_rthdr_space.3
|
||||||
./usr/share/man/man3/inet_addr.3
|
./usr/share/man/man3/inet_addr.3
|
||||||
./usr/share/man/man3/inet_aton.3
|
./usr/share/man/man3/inet_aton.3
|
||||||
./usr/share/man/man3/inet_lnaof.3
|
./usr/share/man/man3/inet_lnaof.3
|
||||||
|
|||||||
@ -1,4 +1,4 @@
|
|||||||
# $NetBSD: Makefile.inc,v 1.45 1999/11/10 22:41:00 jdolecek Exp $
|
# $NetBSD: Makefile.inc,v 1.46 1999/12/12 11:20:04 itojun Exp $
|
||||||
# @(#)Makefile.inc 8.2 (Berkeley) 9/5/93
|
# @(#)Makefile.inc 8.2 (Berkeley) 9/5/93
|
||||||
|
|
||||||
# net sources
|
# net sources
|
||||||
@ -71,10 +71,23 @@ MLINKS+=resolver.3 dn_comp.3 resolver.3 dn_expand.3 resolver.3 res_init.3 \
|
|||||||
resolver.3 res_search.3
|
resolver.3 res_search.3
|
||||||
|
|
||||||
# IPv6
|
# IPv6
|
||||||
MAN+= getaddrinfo.3 getnameinfo.3 if_indextoname.3
|
MAN+= getaddrinfo.3 getnameinfo.3 if_indextoname.3 \
|
||||||
|
inet6_option_space.3 inet6_rthdr_space.3
|
||||||
MLINKS+=getaddrinfo.3 freeaddrinfo.3 getaddrinfo.3 gai_strerror.3 \
|
MLINKS+=getaddrinfo.3 freeaddrinfo.3 getaddrinfo.3 gai_strerror.3 \
|
||||||
if_indextoname.3 if_nametoindex.3 if_indextoname.3 if_nameindex.3 \
|
if_indextoname.3 if_nametoindex.3 if_indextoname.3 if_nameindex.3 \
|
||||||
if_indextoname.3 if_freenameindex.3 \
|
if_indextoname.3 if_freenameindex.3 \
|
||||||
|
inet6_option_space.3 inet6_option_init.3 \
|
||||||
|
inet6_option_space.3 inet6_option_append.3 \
|
||||||
|
inet6_option_space.3 inet6_option_alloc.3 \
|
||||||
|
inet6_option_space.3 inet6_option_next.3 \
|
||||||
|
inet6_option_space.3 inet6_option_find.3 \
|
||||||
|
inet6_rthdr_space.3 inet6_rthdr_init.3 \
|
||||||
|
inet6_rthdr_space.3 inet6_rthdr_add.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 \
|
||||||
|
inet6_rthdr_space.3 inet6_rthdr_getaddr.3 \
|
||||||
|
inet6_rthdr_space.3 inet6_rthdr_getflags.3
|
||||||
# need to revisit
|
# need to revisit
|
||||||
#MAN+= getipnodebyname.3 rresvport_af.3
|
#MAN+= getipnodebyname.3 rresvport_af.3
|
||||||
#MLINKS+=getipnodebyname.3 getipnodebyaddr.3 getipnodebyname.3 freehostent.3 \
|
#MLINKS+=getipnodebyname.3 getipnodebyaddr.3 getipnodebyname.3 freehostent.3 \
|
||||||
|
|||||||
451
lib/libc/net/inet6_option_space.3
Normal file
451
lib/libc/net/inet6_option_space.3
Normal file
@ -0,0 +1,451 @@
|
|||||||
|
.\" $NetBSD: inet6_option_space.3,v 1.1 1999/12/12 11:20:04 itojun Exp $
|
||||||
|
.\"
|
||||||
|
.\" 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.
|
||||||
|
.\"
|
||||||
|
.\" KAME Id: inet6_option_space.3,v 1.3 1999/12/10 07:01:02 itojun Exp
|
||||||
|
.\"
|
||||||
|
.Dd December 10, 1999
|
||||||
|
.Dt INET6_OPTION_SPACE 3
|
||||||
|
.Os
|
||||||
|
.\"
|
||||||
|
.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
|
||||||
|
are documented in
|
||||||
|
.Dq Advanced Sockets API for IPv6
|
||||||
|
.Pq RFC2292 .
|
||||||
|
.\"
|
||||||
|
.Sh BUGS
|
||||||
|
The text was shamelessly copied from RFC2292.
|
||||||
321
lib/libc/net/inet6_rthdr_space.3
Normal file
321
lib/libc/net/inet6_rthdr_space.3
Normal file
@ -0,0 +1,321 @@
|
|||||||
|
.\" $NetBSD: inet6_rthdr_space.3,v 1.1 1999/12/12 11:20:05 itojun Exp $
|
||||||
|
.\"
|
||||||
|
.\" 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.
|
||||||
|
.\"
|
||||||
|
.\" KAME Id: inet6_rthdr_space.3,v 1.2 1999/12/10 07:01:02 itojun Exp
|
||||||
|
.\"
|
||||||
|
.Dd December 10, 1999
|
||||||
|
.Dt INET6_OPTION_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
|
||||||
|
.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 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
|
||||||
|
are documented in
|
||||||
|
.Dq Advanced Sockets API for IPv6
|
||||||
|
.Pq RFC2292 .
|
||||||
|
.\"
|
||||||
|
.Sh BUGS
|
||||||
|
The text was shamelessly copied from RFC2292.
|
||||||
Loading…
Reference in New Issue
Block a user