Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > I

inet6_opt_init(3N)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

inet6_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);

DESCRIPTION

These 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 VALUE

inet6_opt_init(), inet6_opt_append(), inet6_opt_finish(), inet6_opt_next(), and inet6_opt_find() return -1 on an error.

EXAMPLES

The Advanced Sockets API for IPv6 (draft-ietf-ipngwg-2292bis-02.txt) document gives a comprehensive example in Appendix C.

AUTHOR

The APIs were developed by HP.

SEE ALSO

IPv6(7P).

Advanced Sockets API for IPv6 (draft-ietf-ipngwg-2292bis-02.txt).

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.