inet6_opt_append()--Append New Option to IPv6 Extension Header

Syntax

  #include <netinet/in.h>

  int inet6_opt_append(void *extension_buffer,
                       socklen_t extension_length,
                       int offset,
                       uint8_t option_type,
                       socklen_t option_length,
                       uint32_t alignment,
                       void **data_bufferp)

  Service Program Name: QSOSRV1IP6

  Default Public Authority: *USE

  Threadsafe: Yes

The inet6_opt_append() function returns the updated total length of the extension header after adding the new option and alignment. If extension_buffer is not NULL, padding will be inserted to align the option, initialize the option by setting the type and length fields, and return a pointer to the location for the option content in data_bufferp.

Parameters

extension_buffer: (Input) Pointer to a buffer that contains an extension header.
extension_length: (Input) Total number of bytes in the buffer pointed to by extension_buffer. Must be a positive multiple of 8.
offset: (Input) Length of the existing extension header.
The value returned from inet6_opt_init() or a previous call to inet6_opt_append() can be used here.
option_type: (Input) Type of option to append.
option_length: (Input) Length of the data portion of the option, excluding type and length fields contained in the header portion of the option.
alignment: (Input) Number of bytes in the boundary alignment.
data_bufferp: (I/O) Pointer to the buffer to store the option(s) data.

Authorities

No authorization is required.

Return Value

inet6_opt_append() returns an integer. Possible values are:

-1 (unsuccessful)
n (successful), where n is the updated total number of bytes in the extension header

Error Conditions

When inet6_opt_append() fails, errno can be set to one of the following:

[EFAULT]

Bad address.

The system detected an address that was not valid while attempting to access the buffer pointed to by the extension_buffer or data_bufferp parameter.

[EINVAL]

Parameter not valid.

This error code indicates one of the following:

The extension_length field contains a value that is not a positive multiple of 8.
The offset field contains a value that is not larger than the size of the hop-by-hop extension header.
The option_type field contains a value that is not in the range from 2 to 255, inclusive.
The option_length field contains a value that is not in the range from 0 to 255, inclusive, or will not fit in the extension header.
The alignment field contains a value other than 1, 2, 4, 8, or exceeds the value of length.

Usage Notes

option_type must have a value in the range 2 to 255 inclusive. 0 and 1 are reserved for the Pad1 and PadN options respectively. The pad options are used to align the options on boundaries.
inet6_opt_append() is normally called twice for each option to be appended to an options header.
The first call is used to update the total length of the extension header based on an option to be appended, as shown in this example:
```
     int currentlen, extlen;
     void *extbuf;
     void *databufp;
     currentlen = inet6_opt_init(NULL, 0);
     currentlen = inet6_opt_append(NULL, 0, currentlen, OPT_X, 12, 8, NULL);
```
After the total length is calculated by calling inet6_opt_append(), as shown in the preceding example, for each option to be added, and by calling inet6_opt_finish() to calculate the final extension length to be used when actually building the extension header, the desired option(s) are appended to the initialized header as follows:
```
     extlen = currentlen; 
     extbuf = malloc(extlen);
     currentlen = inet6_opt_init(extbuf, extlen);
     currentlen = inet6_opt_append(extbuf, extlen, currentlen, OPT_X, 12, 8, &databufp);
```
After inet6_opt_append() has been called, the application can use databufp directly or use inet6_opt_set_val() to specify the content of the option.

Related Information

inet6_opt_find()--Extract Option of Specified Type from IPv6 Extension Header
inet6_opt_finish()--Finish Adding Options to IPv6 Extension Header
inet6_opt_get_val()--Retrieve Data Item from an IPv6 Option
inet6_opt_init()--Get Length of IPv6 Extension Header
inet6_opt_next()--Extract the Next Option from the IPv6 Extension Header
inet6_opt_set_val()--Insert Data Items into IPv6 Option

API introduced: V6R1

[ Back to top | UNIX-Type APIs | APIs by category ]