320 lines
8.5 KiB
Groff
320 lines
8.5 KiB
Groff
.\" $KAME: inet6_opt_init.3,v 1.5 2002/10/17 14:13:47 jinmei Exp $
|
|
.\"
|
|
.\" Copyright (C) 2000 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd February 5, 2000
|
|
.Dt INET6_OPT_INIT 3
|
|
.Os
|
|
.\"
|
|
.Sh NAME
|
|
.Nm inet6_opt_init ,
|
|
.Nm inet6_opt_append ,
|
|
.Nm inet6_opt_finish ,
|
|
.Nm inet6_opt_set_val ,
|
|
.Nm inet6_opt_next ,
|
|
.Nm inet6_opt_find ,
|
|
.Nm inet6_opt_get_val
|
|
.Nd IPv6 Hop-by-Hop and Destination Options manipulation
|
|
.\"
|
|
.Sh SYNOPSIS
|
|
.In netinet/in.h
|
|
.Ft "int"
|
|
.Fn inet6_opt_init "void *extbuf" "socklen_t extlen"
|
|
.Ft "int"
|
|
.Fn inet6_opt_append "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t len" "u_int8_t align" "void **databufp"
|
|
.Ft "int"
|
|
.Fn inet6_opt_finish "void *extbuf" "socklen_t extlen" "int offset"
|
|
.Ft "int"
|
|
.Fn inet6_opt_set_val "void *databuf" "int offset" "void *val" "socklen_t vallen"
|
|
.Ft "int"
|
|
.Fn inet6_opt_next "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t *typep" "socklen_t *lenp" "void **databufp"
|
|
.Ft "int"
|
|
.Fn inet6_opt_find "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t *lenp" "void **databufp"
|
|
.Ft "int"
|
|
.Fn inet6_opt_get_val "void *databuf" "socklen_t offset" "void *val" "socklen_t vallen"
|
|
.\"
|
|
.Sh DESCRIPTION
|
|
Building and parsing the Hop-by-Hop and Destination options is
|
|
complicated.
|
|
The advanced API therefore defines a set
|
|
of functions to help applications.
|
|
These functions assume the
|
|
formatting rules specified in Appendix B in RFC2460, i.e., that the
|
|
largest field is placed last in the option.
|
|
The function prototypes for
|
|
these functions are all in the
|
|
.In netinet/in.h
|
|
header.
|
|
.\"
|
|
.Ss inet6_opt_init
|
|
The
|
|
.Fn inet6_opt_init
|
|
function
|
|
returns the number of bytes needed for the empty
|
|
extension header, i.e., without any options.
|
|
If
|
|
.Va extbuf
|
|
is not
|
|
.Dv NULL
|
|
it also initializes the extension header to have the correct length
|
|
field.
|
|
In that case if the
|
|
.Fa extlen
|
|
value is not a positive
|
|
(i.e., non-zero)
|
|
multiple of 8 the function fails and returns \-1.
|
|
.\"
|
|
.Ss inet6_opt_append
|
|
The
|
|
.Fn inet6_opt_append
|
|
function
|
|
returns the updated total length taking into account
|
|
adding an option with length
|
|
.Fa len
|
|
and alignment
|
|
.Fa align .
|
|
The
|
|
.Fa offset
|
|
argument
|
|
should be the length returned by
|
|
.Fn inet6_opt_init
|
|
or a previous
|
|
.Fn inet6_opt_append .
|
|
If
|
|
.Fa extbuf
|
|
is not
|
|
.Dv NULL
|
|
then, in addition to returning the length,
|
|
the function inserts any needed pad option, initializes the option
|
|
(setting the type and length fields)
|
|
and returns a pointer to the location for the option content in
|
|
.Fa databufp .
|
|
.Pp
|
|
The
|
|
.Fa type
|
|
argument
|
|
is the 8-bit option type.
|
|
The
|
|
.Fa len
|
|
argument
|
|
is the length of the option data
|
|
(i.e., excluding the option type and option length fields).
|
|
.Pp
|
|
Once
|
|
.Fn inet6_opt_append
|
|
has been called, the application can use the
|
|
databuf directly, or use
|
|
.Fn inet6_opt_set_val
|
|
to specify the content of the option.
|
|
.Pp
|
|
The option type must have a value from 2 to 255, inclusive.
|
|
(0 and 1 are reserved for the Pad1 and PadN options, respectively.)
|
|
.Pp
|
|
The option data length must have a value between 0 and 255,
|
|
inclusive, and is the length of the option data that follows.
|
|
.Pp
|
|
The
|
|
.Fa align
|
|
parameter must have a value of 1, 2, 4, or 8.
|
|
The align value can not exceed the value of
|
|
.Fa len .
|
|
.\"
|
|
.Ss inet6_opt_finish
|
|
The
|
|
.Fn inet6_opt_finish
|
|
function
|
|
returns the updated total length
|
|
taking into account the final padding of the extension header to make
|
|
it a multiple of 8 bytes.
|
|
The
|
|
.Fa offset
|
|
argument
|
|
should be the length returned by
|
|
.Fn inet6_opt_init
|
|
or
|
|
.Fn inet6_opt_append .
|
|
If
|
|
.Fa extbuf
|
|
is not
|
|
.Dv NULL
|
|
the function also
|
|
initializes the option by inserting a Pad1 or PadN option of the
|
|
proper length.
|
|
.Pp
|
|
If the necessary pad does not fit in the extension header buffer the
|
|
function returns \-1.
|
|
.\"
|
|
.Ss inet6_opt_set_val
|
|
The
|
|
.Fn inet6_opt_set_val
|
|
function
|
|
inserts data items of various sizes in the data portion of the option.
|
|
The
|
|
.Fa databuf
|
|
argument
|
|
should be a pointer returned by
|
|
.Fn inet6_opt_append .
|
|
The
|
|
.Fa val
|
|
argument
|
|
should point to the data to be
|
|
inserted.
|
|
The
|
|
.Fa offset
|
|
argument
|
|
specifies where in the data portion of the option
|
|
the value should be inserted; the first byte after the option type
|
|
and length is accessed by specifying an offset of zero.
|
|
.Pp
|
|
The caller should ensure that each field is aligned on its natural
|
|
boundaries as described in Appendix B of RFC2460, but the function
|
|
must not rely on the caller's behavior.
|
|
Even when the alignment requirement is not satisfied,
|
|
the function should just copy the data as required.
|
|
.Pp
|
|
The function returns the offset for the next field
|
|
(i.e.,
|
|
.Fa offset
|
|
+
|
|
.Fa vallen )
|
|
which can be used when composing option content with multiple fields.
|
|
.\"
|
|
.Ss inet6_opt_next
|
|
The
|
|
.Fn inet6_opt_next
|
|
function
|
|
parses received extension headers returning the next
|
|
option.
|
|
The
|
|
.Fa extbuf
|
|
and
|
|
.Fa extlen
|
|
arguments specify the extension header.
|
|
The
|
|
.Fa offset
|
|
argument
|
|
should either be zero (for the first option), or the length returned
|
|
by a previous call to
|
|
.Fn inet6_opt_next
|
|
or
|
|
.Fn inet6_opt_find .
|
|
It specifies the position where to continue scanning the extension
|
|
buffer.
|
|
The next option is returned by updating
|
|
.Fa typep , lenp ,
|
|
and
|
|
.Fa databufp .
|
|
This function returns the updated
|
|
.Dq previous
|
|
length
|
|
computed by advancing past the option that was returned.
|
|
This returned
|
|
.Dq previous
|
|
length can then be passed to subsequent calls to
|
|
.Fn inet6_opt_next .
|
|
This function does not return any PAD1 or PADN options.
|
|
When there are no more options the return value is \-1.
|
|
.\"
|
|
.Ss inet6_opt_get_val
|
|
The
|
|
.Fn inet6_opt_get_val
|
|
function extracts data items of various sizes
|
|
in the data portion of the option.
|
|
The
|
|
.Fa databuf
|
|
argument
|
|
should be a pointer returned by
|
|
.Fn inet6_opt_next
|
|
or
|
|
.Fn inet6_opt_find .
|
|
The
|
|
.Fa val
|
|
argument
|
|
should point to the destination for the extracted data.
|
|
The
|
|
.Fa offset
|
|
argument
|
|
specifies from where in the data portion of the option the value should be
|
|
extracted; the first byte after the option type and length is
|
|
accessed by specifying an offset of zero.
|
|
.Pp
|
|
It is expected that each field is aligned on its natural boundaries
|
|
as described in Appendix B of RFC2460, but the function must not
|
|
rely on the alignment.
|
|
.Pp
|
|
The function returns the offset for the next field
|
|
(i.e.,
|
|
.Fa offset
|
|
+
|
|
.Fa vallen )
|
|
which can be used when extracting option content with
|
|
multiple fields.
|
|
Robust receivers might want to verify alignment before calling
|
|
this function.
|
|
.\"
|
|
.Sh DIAGNOSTICS
|
|
All the functions return
|
|
\-1
|
|
on an error.
|
|
.\"
|
|
.Sh EXAMPLES
|
|
draft-ietf-ipngwg-rfc2292bis-08.txt
|
|
gives comprehensive examples in Section 23.
|
|
.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 draft-ietf-ipngwg-rfc2292bis-08
|
|
.%D October 2002
|
|
.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 draft-ietf-ipngwg-rfc2292bis-08.txt .
|
|
.\"
|
|
.Sh BUGS
|
|
The text was shamelessly copied from internet-drafts for RFC2292bis.
|