 |
» |
|
|
|
NAMEinet6_opt_init(), inet6_opt_append(), inet6_opt_find(), inet6_opt_finish(), inet6_opt_get_val(), inet6_opt_next(), inet6_opt_set_val() — IPv6 Hop-by-Hop and Destination options manipulation functions SYNOPSIS#include <netinet/in.h>
int inet6_opt_append(void *extbuf, size_t extlen, int prevlen,
uint8_t type, size_t len, uint_t align,
void **databufp);
int inet6_opt_find(void *extbuf, size_t extlen, int prevlen,
uint8_t type, size_t *lenp,
void **databufp);
int inet6_opt_finish(void *extbuf, size_t extlen, int prevlen);
int inet6_opt_get_val(void *databuf, size_t offset, void *val,
int vallen);
int inet6_opt_init(void *extbuf, size_t extlen);
int inet6_opt_next(void *extbuf, size_t extlen, int prevlen,
uint8_t *typep, size_t *lenp,
void **databufp);
int inet6_opt_set_val(void *databuf, size_t offset, void *val,
int vallen); DESCRIPTIONThese functions can be used by applications to build and parse the IPv6
Hop-by-Hop and Destination options header.
The Hop-by-Hop option header is used to carry optional information
that must be examined by every node along a packet's delivery path
and the Destination option header is used to carry optional information
that needs to be examined only by a packet's destination node(s). To receive Hop-by-Hop options the application must enable the
IPV6_RECVHOPOPTS
socket option: int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPOPTS, &on, sizeof(on)); To send a Hop-by-Hop options header, the application specifies the
header either as ancillary data in a call to
sendmsg()
or using
setsockopt(). The application can remove any sticky Hop-by-Hop extension header by
calling
setsockopt()
for
IPV6_HOPOPTS
with a zero option length. To receive Destination options appearing after a Routing header (or
in a packet without a Routing header) the application must enable the
IPV6_RECVDSTOPTS
socket option: int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on)); To receive Destination options appearing before a Routing header the
application must enable the
IPV6_RECVRTHDRDSTOPTS
socket option: int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDRDSTOPTS, &on, sizeof(on)); To send a Destination options header, the application specifies it
either as ancillary data in a call to
sendmsg()
or using
setsockopt(). The application can remove any sticky Destination extension header by
calling
setsockopt()
for
IPV6_RTHDRDSTOPTS/IPV6_DSTOPTS
with a zero
option length.
- inet6_opt_init()
This function returns the number of bytes needed for the empty
extension header without any options.
If
extbuf
is not NULL, it
also initializes the extension header to have the correct length field.
If the
extlen
value is not a positive multiple of 8, the function fails and returns -1. - inet6_opt_append()
This function returns the updated total
length required to add an option with length
len
and alignment
align.
If
extbuf
is not NULL, then
in addition to returning the length, this function also
inserts any needed pad option,
initializes the option (sets the type and length fields), and
returns a pointer to the location for the option content in
databufp.
If the
option specified by the
type
does not fit in the extension header buffer
then the
function returns -1. The third parameter
prevlen
should be the length returned by
inet6_opt_init()
or by a previous
inet6_opt_append(). The parameter
type
is the 8-bit option type
and it must be a value from 2 to 255, inclusive.
0 and 1
are reserved for the Pad1 and PadN options, respectively. The parameter
len
is the length of the option data
excluding the option type and option length fields.
It must have a value between 0 and 255,
inclusive, and it specifies the length of the option data that follows
the option header. The
align
parameter must have a value of 1, 2, 4, or 8.
The
align
value can not exceed the value of
len. Once
inet6_opt_append()
has been called, the application can use
databuf
directly, or use
inet6_opt_set_val()
to specify (set) the contents of the option. - inet6_opt_finish()
This function returns the updated total length
including the final padding of the extension header to
make the header a multiple of 8 bytes. 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. The parameter
prevlen
should be the length returned by
inet6_opt_init()
or
inet6_opt_append(). - inet6_opt_set_val()
This
function inserts data items of various sizes (1, 2, 4, or 8 bytes) in
the data portion of the option.
After inserting,
the function returns the offset for the next field
(offset +
vallen)
which can be used when composing option content with multiple
fields.
The parameter
val
points to the data to be inserted and
the parameter
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 parameter
databuf
should be a pointer returned by
inet6_opt_append(). - inet6_opt_next()
This function parses extension header options received by the
application and it returns the offset of the
next option. The parameters
extbuf
and
extlen
specify the extension header. The parameter
prevlen
is either zero (for the first option) or the length
returned by a previous call to
inet6_opt_next()
or
inet6_opt_find().
prevlen
specifies the position where to continue scanning the extension
buffer.
The next option is returned by updating the parameters
databufp
typep,
and
lenp.
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 or if the option extension
header is malformed, the return value is -1. - inet6_opt_find()
This function is similar to the
inet6_opt_next()
function but this function lets the caller specify the option
type to be searched for instead of always
returning the next option
in the extension header. If an option of the specified
type
is located, the function returns
the updated "previous" total length.
This "previous" total length is computed by advancing past the
option that was returned and past any options that did not match the
type.
This returned previous
length
can then be passed to
subsequent calls to
inet6_opt_find()
for finding the next occurrence
of the same option type. If an option of the specified
type
is not located or the option extension header
is malformed, the return value is -1. - 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.
The function returns the offset for the next field
(offset +
vallen)
which can be used when extracting option content with
multiple fields. The first parameter
databuf
should be a pointer returned by
inet6_opt_next()
or
inet6_opt_find()
containing the data portion of the option. offset
parameter 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. val
points to the destination for the extracted data.
To use these functions, the application must be compiled with:
-D_HPUX_SOURCE
-D_XOPEN_SOURCE_EXTENDED
-lxnet
-lipv6
These APIs are implemented based on internet-draft
Advanced Sockets API for IPv6
(draft-ietf-ipngwg-2292bis-02.txt).
The APIs may be updated, replaced, or
obsoleted based on future changes to the document. RETURN VALUEinet6_opt_init(),
inet6_opt_append(),
inet6_opt_finish(),
inet6_opt_next(),
and
inet6_opt_find()
return -1 on an error. EXAMPLESThe
Advanced Sockets API for IPv6
(draft-ietf-ipngwg-2292bis-02.txt)
document gives a comprehensive example in Appendix C. AUTHORThe APIs were developed by HP. SEE ALSOIPv6(7P). Advanced Sockets API for IPv6
(draft-ietf-ipngwg-2292bis-02.txt).
|
Printable version
