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.