INET6_OPT_INIT(3) BSD Programmer's Manual INET6_OPT_INIT(3)NAME
inet6_opt_init, inet6_opt_append, inet6_opt_finish, inet6_opt_set_val,
inet6_opt_next, inet6_opt_find, inet6_opt_get_val, - IPv6 Hop-by-Hop and
Destination Options manipulation
SYNOPSIS
#include <netinet/in.h>
int
inet6_opt_init(void *extbuf, size_t extlen);
int
inet6_opt_append(void *extbuf, size_t extlen, int prevlen, u_int8_t type,
size_t len, u_int8_t align, void **databufp);
int
inet6_opt_finish(void *extbuf, size_t extlen, int prevlen);
int
inet6_opt_set_val(void *databuf, size_t offset, void *val, int vallen);
int
inet6_opt_next(void *extbuf, size_t extlen, int prevlen, u_int8_t *typep,
size_t *lenp, void **databufp);
int
inet6_opt_find(void *extbuf, size_t extlen, int prevlen, u_int8_t type,
size_t *lenp, void **databufp);
int
inet6_opt_get_val(void *databuf, size_t offset, void *val, int vallen);
DESCRIPTION
Building and parsing the Hop-by-Hop and Destination options is complicat-
ed for the reasons given earlier. The advanced API therefore defines a
set of functions to help applications. These functions assume the for-
matting 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 <netinet/in.h> header.
inet6_opt_init
inet6_opt_init() returns the number of bytes needed for the empty exten-
sion header i.e. without any options. If extbuf is not NULL it also ini-
tializes the extension header to have the correctlength field. If the
extlen value is not a positive (i.e., non-zero) multiple of 8 the func-
tion fails and returns -1.
inet6_opt_append
inet6_opt_append() returns the updated total length taking into account
adding an option with length len and alignment align. Prevlen should be
the length returned by inet6_opt_init() or a previous inet6_opt_append().
If extbuf is not 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 databufp.
type is the 8-bit option type. len is the length of the option data
(i.e. excluding the option type and option length fields.)
Once inet6_opt_append() has been called the application can use the
databuf directly, or use inet6_opt_set_val() to specify the content of
the option.
The option type must have a value from 2 to 255, inclusive. (0 and 1 are
reserved for the Pad1 and PadN options, respectively.)
The option data length must have a value between 0 and 255, inclusive,
and is the length of the option data that follows.
The align parameter must have a value of 1, 2, 4, or 8. The align value
can not exceed the value of len.
inet6_opt_finish
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. Prevlen should be the length returned by inet6_opt_init() or
inet6_opt_append(). If extbuf is not NULL the function also initializes
the option by inserting a Pad1 or PadN option of the proper length.
If the necessary pad does not fit in the extension header buffer the
function returns -1.
inet6_opt_set_valinet6_opt_set_val() inserts data items of various sizesm (1, 2, 4, or 8
bytes) in the data portion of the option. Databuf should be a pointer re-
turned by inet6_opt_append(). val should point to the data to be insert-
ed. 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.
The function returns the offset for the next field (i.e., offset +
vallen) which can be used when composing option content with multiple
fields.
inet6_opt_next
inet6_opt_next() parses received extension headers returning the next op-
tion. Extbuf and extlen specifies the extension header. Prevlen should
either be zero (for the first option) or the length returned by a previ-
ous call to inet6_opt_next() or inet6_opt_find(). It specifies the posi-
tion where to continue scanning the extension buffer. The next option is
returned by updating typep, lenp, and databufp. This function returns the
updated ``previous'' length computed by advancing past the option that
was returned. This returned ``previous'' length can then be passed to
subsequent calls to inet6_opt_next(). This function does not return any
PAD1 or PADN options. When there are no more options the return value is
-1.
inet6_opt_get_val
inet6_opt_get_val() This function extracts data items of various sizes
(1, 2, 4, or 8 bytes) in the data portion of the option. Databuf should
be a pointer returned by inet6_opt_next() or inet6_opt_find(). Val
should point to the destination for the extracted data. Offset specifies
from where in the data portion of the option the value should be extract-
ed; the first byte after the option type and length is accessed by speci-
fying an offset of zero.
The function returns the offset for the next field (i.e., offset +
vallen) which can be used when extracting option content with multiple
fields. Robust receivers might want to verify alignment before calling
this function.
DIAGNOSTICS
All the functions ruturn -1 on an error.
EXAMPLES
draft-ietf-ipngwg-rfc2292bis-01.txt gives comprehensive examples in Sec-
tion 24.
KAME also provides examples in the advapi directry of its kit.
SEE ALSO
W. Stevens, M. Thomas, and E. Nordmark, Advanced Sockets API for IPv6,
draft-ietf-ipngwg-rfc2292bis-01, October 1999.
S. Deering, and R. Hinden, Internet Protocol, Version 6 (IPv6)
Specification, RFC2460, December 1998.
HISTORY
The implementation first appeared in KAME advanced networking kit.
STANDARDS
The functions are documented in ``Advanced Sockets API for IPv6''
(draft-ietf-ipngwg-rfc2292bis-01.txt).
BUGS
RFC2292bis is still under standardization procedure. The specification
of the functions described in this manual can be changed in the future.
The text was shamelessly copied from internet-drafts for RFC2292bis.
KAME February 5, 2000 3
