INET6_OPT(3SOCKET) Sockets Library Functions INET6_OPT(3SOCKET)

NAME

inet6_opt, inet6_opt_init, inet6_opt_append, inet6_opt_finish,
inet6_opt_set_val, inet6_opt_next, inet6_opt_find, inet6_opt_get_val
- Option manipulation mechanism

SYNOPSIS

cc [ flag ... ] file ... -lsocket [library...]
#include <netinet/in.h>

int inet6_opt_init(void *extbuf, socklen_t extlen);


int inet6_opt_append(void *extbuf, socklen_t extlen,
int offset, uint8_t type, socklen_t len, uint_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, uint8_t *typep, socklen_t *lenp,
void **databufp);


int inet6_opt_find(void *extbuf, socklen_t extlen, int offset,
uint8_t type, socklen_t *lenp, void **databufp);


int inet6_opt_get_val(void *databuf, int offset,
void *val, socklen_t *vallen);

DESCRIPTION

The inet6_opt functions enable users to manipulate options without
having to know the structure of the option header.


The inet6_opt_init() function returns the number of bytes needed for
the empty extension header, that is, without any options. If extbuf
is not NULL, it also initializes the extension header to the correct
length field. If the extlen value is not a positive non-zero multiple
of 8, the function fails and returns -1.


The inet6_opt_append() function returns the updated total length
while adding an option with length len and alignment align. 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. If the option does not fit in the
extension header buffer, the function returns -1. The type is the
8-bit option type. The len is the length of the option data,
excluding the option type and option length fields. Once
inet6_opt_append() is called, the application can use the databuf
directly, or inet6_opt_set_val() can be used to specify the content
of the option. The option type must have a value from 2 to 255,
inclusive. The values 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 it 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 cannot exceed the value of len.


The inet6_opt_finish() function returns the updated total length the
takes into account the final padding of the extension header to make
it 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 inet6_opt_set_val() function inserts data items of various sizes
in the data portion of the option. The val parameter should point to
the data to be inserted. The offset specifies the data portion of the
option in which the value should be inserted. The first byte after
the option type and length is accessed by specifying an offset of
zero.


The inet6_opt_next() function parses the received option extension
headers which return the next option. The extbuf and extlen
parameters specify the extension header. The offset should be zero
for the first option or the length returned by a previous call to
either inet6_opt_next() or inet6_opt_find(). The offset specifies
where to continue scanning the extension buffer. The subsequent
option is returned by updating typep, lenp, and databufp. The typep
argument stores the option type. The lenp argument stores the length
of the option data, excluding the option type and option length
fields. The databufp argument points to the data field of the
option.


The inet6_opt_find() function is similar to the inet6_opt_next()
function. Unlike inet6_opt_next(), the inet6_opt_find() function
enables the caller to specify the option type to be searched for,
rather than returning the next option in the extension header.


The inet6_opt_get_val() function extracts data items of various sizes
in the portion of the option. The val argument should point to the
destination for the extracted data. The offset specifies at which
point in the option's data portion the value should be extracted. The
first byte following the option type and length is accessed by
specifying an offset of zero.

RETURN VALUES

The inet6_opt_init() function returns the number of bytes needed for
the empty extension header. If the extlen value is not a positive
non-zero multiple of 8, the function fails and returns -1.


The inet6_opt_append() function returns the updated total length.


The inet6_opt_finish() function returns the updated total length.


The inet6_opt_set_val() function returns the offset for the
subsequent field.


The inet6_opt_next() function returns the updated "previous" length
computed by advancing past the option that was returned. When there
are no additional options or if the option extension header is
malformed, the return value is -1.


The inet6_opt_find() function returns the updated "previous" total
length. If an option of the specified type is not located, the return
value is -1. If the option extension header is malformed, the return
value is -1.


The inet6_opt_get_val() function returns the offset for the next
field (that is, offset + vallen) which can be used when extracting
option content with multiple fields.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+

SEE ALSO

RFC 3542 - Advanced Sockets Application Programming Interface (API)
for IPv6, The Internet Society. May 2003

June 13, 2021 INET6_OPT(3SOCKET)