Query: inet6_option_next
OS: netbsd
Section: 3
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
INET6_OPTION_SPACE(3) BSD Library Functions Manual INET6_OPTION_SPACE(3)NAMEinet6_option_space, inet6_option_init, inet6_option_append, inet6_option_alloc, inet6_option_next, inet6_option_find -- IPv6 Hop-by-Hop and Destination Options manipulationSYNOPSIS#include <netinet/in.h> int inet6_option_space(int nbytes); int inet6_option_init(void *bp, struct cmsghdr **cmsgp, int type); int inet6_option_append(struct cmsghdr *cmsg, const uint8_t *typep, int multx, int plusy); uint8_t * inet6_option_alloc(struct cmsghdr *cmsg, int datalen, int multx, int plusy); int inet6_option_next(const struct cmsghdr *cmsg, uint8_t **tptrp); int inet6_option_find(const struct cmsghdr *cmsg, uint8_t **tptrp, int type);DESCRIPTIONBuilding and parsing the Hop-by-Hop and Destination options is complicated due to alignment constraints, padding and ancillary data manipula- tion. RFC 2292 defines a set of functions to help the application. The function prototypes for these functions are all in the <netinet/in.h> header. inet6_option_space inet6_option_space() returns the number of bytes required to hold an option when it is stored as ancillary data, including the cmsghdr struc- ture at the beginning, and any padding at the end (to make its size a multiple of 8 bytes). The argument is the size of the structure defin- ing the option, which must include any pad bytes at the beginning (the value y in the alignment term ``xn + y''), the type byte, the length byte, and the option data. Note: If multiple options are stored in a single ancillary data object, which is the recommended technique, this function overestimates the amount of space required by the size of N-1 cmsghdr structures, where N is the number of options to be stored in the object. This is of lit- tle consequence, since it is assumed that most Hop-by-Hop option headers and Destination option headers carry only one option (appendix B of [RFC 2460]). inet6_option_init inet6_option_init() is called once per ancillary data object that will contain either Hop-by-Hop or Destination options. It returns 0 on success or -1 on an error. bp is a pointer to previously allocated space that will contain the ancillary data object. It must be large enough to contain all the indi- vidual options to be added by later calls to inet6_option_append() and inet6_option_alloc(). cmsgp is a pointer to a pointer to a cmsghdr structure. *cmsgp is initialized by this function to point to the cmsghdr structure constructed by this function in the buffer pointed to by bp. type is either IPV6_HOPOPTS or IPV6_DSTOPTS. This type is stored in the cmsg_type member of the cmsghdr structure pointed to by *cmsgp. inet6_option_append This function appends a Hop-by-Hop option or a Destination option into an ancillary data object that has been initialized by inet6_option_init(). This function returns 0 if it succeeds or -1 on an error. cmsg is a pointer to the cmsghdr structure that must have been initialized by inet6_option_init(). typep is a pointer to the 8-bit option type. It is assumed that this field is immediately followed by the 8-bit option data length field, which is then followed immediately by the option data. The caller initializes these three fields (the type-length-value, or TLV) before calling this function. The option type must have a value from 2 to 255, inclusive. (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 is the length of the option data that follows. multx is the value x in the alignment term ``xn + y''. It must have a value of 1, 2, 4, or 8. plusy is the value y in the alignment term ``xn + y''. It must have a value between 0 and 7, inclusive. inet6_option_alloc This function appends a Hop-by-Hop option or a Destination option into an ancillary data object that has been initialized by inet6_option_init(). This function returns a pointer to the 8-bit option type field that starts the option on success, or NULL on an error. The difference between this function and inet6_option_append() is that the latter copies the contents of a previously built option into the ancillary data object while the current function returns a pointer to the space in the data object where the option's TLV must then be built by the caller. cmsg is a pointer to the cmsghdr structure that must have been initialized by inet6_option_init(). datalen is the value of the option data length byte for this option. This value is required as an argument to allow the function to deter- mine if padding must be appended at the end of the option. (The inet6_option_append() function does not need a data length argument since the option data length must already be stored by the caller.) multx is the value x in the alignment term ``xn + y''. It must have a value of 1, 2, 4, or 8. plusy is the value y in the alignment term ``xn + y''. It must have a value between 0 and 7, inclusive. inet6_option_next This function processes the next Hop-by-Hop option or Destination option in an ancillary data object. If another option remains to be pro- cessed, the return value of the function is 0 and *tptrp points to the 8-bit option type field (which is followed by the 8-bit option data length, followed by the option data). If no more options remain to be processed, the return value is -1 and *tptrp is NULL. If an error occurs, the return value is -1 and *tptrp is not NULL. cmsg is a pointer to cmsghdr structure of which cmsg_level equals IPPROTO_IPV6 and cmsg_type equals either IPV6_HOPOPTS or IPV6_DSTOPTS. tptrp is a pointer to a pointer to an 8-bit byte and *tptrp is used by the function to remember its place in the ancillary data object each time the function is called. The first time this function is called for a given ancillary data object, *tptrp must be set to NULL. Each time this function returns success, *tptrp points to the 8-bit option type field for the next option to be processed. inet6_option_find This function is similar to the previously described inet6_option_next() function, except this function lets the caller specify the option type to be searched for, instead of always returning the next option in the ancillary data object. cmsg is a pointer to cmsghdr structure of which cmsg_level equals IPPROTO_IPV6 and cmsg_type equals either IPV6_HOPOPTS or IPV6_DSTOPTS. tptrp is a pointer to a pointer to an 8-bit byte and *tptrp is used by the function to remember its place in the ancillary data object each time the function is called. The first time this function is called for a given ancillary data object, *tptrp must be set to NULL. ~ This function starts searching for an option of the specified type beginning after the value of *tptrp. If an option of the specified type is located, this function returns 0 and *tptrp points to the 8- bit option type field for the option of the specified type. If an option of the specified type is not located, the return value is -1 and *tptrp is NULL. If an error occurs, the return value is -1 and *tptrp is not NULL.EXAMPLESRFC 2292 gives comprehensive examples in chapter 6.DIAGNOSTICSinet6_option_init() and inet6_option_append() return 0 on success or -1 on an error. inet6_option_alloc() returns NULL on an error. On errors, inet6_option_next() and inet6_option_find() return -1 setting *tptrp to non NULL value.SEE ALSOW. Stevens and M. Thomas, Advanced Sockets API for IPv6, RFC 2292, February 1998. S. Deering and R. Hinden, Internet Protocol, Version 6 (IPv6) Specification, RFC 2460, December 1998.STANDARDSThe functions are documented in ``Advanced Sockets API for IPv6'' (RFC 2292).HISTORYThe implementation first appeared in KAME advanced networking kit.BUGSThe text was shamelessly copied from RFC 2292.BSDDecember 10, 1999 BSD