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

  #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)

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:

Usage Notes

1. 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.
2. 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

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