|
|
INET6_OPT_INIT(3)
Contents
|
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
#include <netinet/in.h>
int
inet6_opt_init(void *extbuf, socklen_t extlen);
int
inet6_opt_append(void *extbuf, socklen_t extlen, int offset,
u_int8_t type, socklen_t len, u_int8_t align, void **databufp);
int
inet6_opt_finish(void *extbuf, socklen_t extlen, int offset);
int
inet6_opt_set_val(void *databuf, int offset, void *val,
socklen_t vallen);
int
inet6_opt_next(void *extbuf, socklen_t extlen, int offset,
u_int8_t *typep, socklen_t *lenp, void **databufp);
int
inet6_opt_find(void *extbuf, socklen_t extlen, int offset, u_int8_t type,
socklen_t *lenp, void **databufp);
int
inet6_opt_get_val(void *databuf, socklen_t offset, void *val,
socklen_t vallen);
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
<netinet/in.h> header.
inet6_opt_init
inet6_opt_init() returns the number of bytes needed for the empty extension
header i.e. without any options. If extbuf is not NULL it also initializes
the extension header to have the correct length field. In that
case if the extlen value is not a positive (i.e., non-zero) multiple of 8
the function 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. Offset 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. Offset 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_val
inet6_opt_set_val() inserts data items of various sizes in the data portion
of the option. Databuf should be a pointer returned by
inet6_opt_append(). val should point to the data to be inserted. 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 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.
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
option. Extbuf and extlen specifies the extension header. Offset should
either be zero (for the first option) or the length returned by a previous
call to inet6_opt_next() or inet6_opt_find(). It specifies the position
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 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 extracted; the first byte after
the option type and length is accessed by specifying an offset of zero.
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.
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.
All the functions ruturn -1 on an error.
draft-ietf-ipngwg-rfc2292bis-08.txt gives comprehensive examples in Section
23.
KAME also provides examples in the advapitest directry of its kit.
W. Stevens, M. Thomas, E. Nordmark, and T. Jinmei, Advanced Sockets API
for IPv6, draft-ietf-ipngwg-rfc2292bis-08, October 2002.
S. Deering and R. Hinden, Internet Protocol, Version 6 (IPv6)
Specification, RFC2460, December 1998.
The implementation first appeared in KAME advanced networking kit.
The functions are documented in ``Advanced Sockets API for IPv6''
(draft-ietf-ipngwg-rfc2292bis-08.txt).
The text was shamelessly copied from internet-drafts for RFC2292bis.
FreeBSD 5.2.1 February 5, 2000 FreeBSD 5.2.1 [ Back ] |
