881c4fa391
(aka RFC2292bis). Though I believe this commit doesn't break backward compatibility againt existing binaries, it breaks backward compatibility of API. Now, the applications which use Advanced Sockets API such as telnet, ping6, mld6query and traceroute6 use RFC3542 API. Obtained from: KAME
292 lines
8.3 KiB
Groff
292 lines
8.3 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
|
|
.Aq Li netinet/in.h
|
|
header.
|
|
.\"
|
|
.Ss inet6_opt_init
|
|
.Fn inet6_opt_init
|
|
returns the number of bytes needed for the empty
|
|
extension header i.e. without any options.
|
|
If
|
|
.Li extbuf
|
|
is not NULL it also initializes the extension header to have the correct length
|
|
field.
|
|
In that case if the
|
|
.Li extlen value is not a positive
|
|
.Po
|
|
i.e., non-zero
|
|
.Pc
|
|
multiple of 8 the function fails and returns -1.
|
|
.\"
|
|
.Ss inet6_opt_append
|
|
.Fn inet6_opt_append
|
|
returns the updated total length taking into account
|
|
adding an option with length
|
|
.Li len
|
|
and alignment
|
|
.Li align .
|
|
.Li Offset
|
|
should be the length returned by
|
|
.Fn inet6_opt_init
|
|
or a previous
|
|
.Fn inet6_opt_append .
|
|
If
|
|
.Li extbuf
|
|
is not NULL then, in addition to returning the length,
|
|
the function inserts any needed pad option, initializes the option
|
|
.Po
|
|
setting the type and length fields
|
|
.Pc
|
|
and returns a pointer to the location for the option content in
|
|
.Li databufp .
|
|
.Pp
|
|
.Li type
|
|
is the 8-bit option type.
|
|
.Li len
|
|
is the length of the option data
|
|
.Po
|
|
i.e. excluding the option type and option length fields.
|
|
.Pc
|
|
.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.
|
|
.Po
|
|
0 and 1 are reserved for the Pad1 and PadN options, respectively.
|
|
.Pc
|
|
.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
|
|
.Li align
|
|
parameter must have a value of 1, 2, 4, or 8.
|
|
The align value can not exceed the value of
|
|
.Li len .
|
|
.\"
|
|
.Ss inet6_opt_finish
|
|
.Fn inet6_opt_finish
|
|
returns the updated total length
|
|
taking into account the final padding of the extension header to make
|
|
it a multiple of 8 bytes.
|
|
.Li Offset
|
|
should be the length returned by
|
|
.Fn inet6_opt_init
|
|
or
|
|
.Fn inet6_opt_append .
|
|
If
|
|
.Li extbuf
|
|
is not 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
|
|
.Fn inet6_opt_set_val
|
|
inserts data items of various sizes in the data portion of the option.
|
|
.Li Databuf
|
|
should be a pointer returned by
|
|
.Fn inet6_opt_append .
|
|
.Li val
|
|
should point to the data to be
|
|
inserted.
|
|
.Li Offset
|
|
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
|
|
.Po
|
|
i.e.,
|
|
.Li offset
|
|
+
|
|
.Li vallen
|
|
.Pc
|
|
which can be used when composing option content with multiple fields.
|
|
.\"
|
|
.Ss inet6_opt_next
|
|
.Fn inet6_opt_next
|
|
parses received extension headers returning the next
|
|
option.
|
|
.Li Extbuf
|
|
and
|
|
.Li extlen
|
|
specifies the extension header.
|
|
.Li Offset
|
|
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
|
|
.Li typep ,
|
|
.Li lenp ,
|
|
and
|
|
.Li 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
|
|
.Fn inet6_opt_get_val
|
|
This function extracts data items of various sizes
|
|
in the data portion of the option.
|
|
.Li Databuf
|
|
should be a pointer returned by
|
|
.Fn inet6_opt_next
|
|
or
|
|
.Fn inet6_opt_find .
|
|
.Li Val
|
|
should point to the destination for the extracted data.
|
|
.Li Offset
|
|
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
|
|
.Po
|
|
i.e.,
|
|
.Li offset
|
|
+
|
|
.Li vallen
|
|
.Pc
|
|
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 ruturn
|
|
.Li -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 directry 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.
|