MirOS Manual: inet6_option_alloc(3), inet6_option_append(3), inet6_option_find(3), inet6_option_init(3), inet6_option_next(3), inet6_option_space(3)

INET6_OPTION_SPACE(3)      BSD Programmer's Manual       INET6_OPTION_SPACE(3)

NAME

     inet6_option_space, inet6_option_init, inet6_option_append,
     inet6_option_alloc, inet6_option_next, inet6_option_find - IPv6 Hop-by-
     Hop and Destination Option Manipulation

SYNOPSIS

     #include <sys/types.h>
     #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 u_int8_t *typep,
             int multx, int plusy);

     u_int8_t *
     inet6_option_alloc(struct cmsghdr *cmsg, int datalen, int multx,
             int plusy);

     int
     inet6_option_next(const struct cmsghdr *cmsg, u_int8_t **tptrp);

     int
     inet6_option_find(const struct cmsghdr *cmsg, u_int8_t **tptrp,
             int type);

DESCRIPTION

     Manipulating and parsing IPv6's Hop-by-Hop and Destination options is
     complicated by the need to properly align and pad data as well as the
     need to manipulate ancillary information that is not part of the data
     stream. RFC 2292 defines a set of functions, which are implemented as
     part of the Kame libraries, to help developers create, change, and parse
     Hop-by-Hop and Destination options. All of the prototypes for the option
     functions are defined in the <netinet/in.h> header file.

inet6_option_space

     In order to determine the amount of space necessary to hold any option
     the inet6_option_space() function is called. It returns the number of
     bytes required to hold an option when it is stored as ancillary data, in-
     cluding the cmsghdr structure at the beginning, and any necessary padding
     at the end. The nbytes argument indicates the size of the structure de-
     fining the option, and 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, the inet6_option_space() 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.
     Usually this has no impact because it is assumed that most Hop-by-Hop and
     Destination option headers carry only one option as indicated in appendix
     B of RFC 2460.

inet6_option_init

     The inet6_option_init() function is called to initialize any ancillary
     data object that will contain a Hop-by-Hop or Destination option. It re-
     turns 0 on success and -1 when an error occurs.

     The bp argument points to a previously allocated area of memory which
     must be large enough to contain all the arguments that the application
     intends to add later via the inet6_option_append() and
     inet6_option_alloc() routines.

     The cmsgp argument is a pointer to a pointer to a cmsghdr structure. The
     *cmsgp argument points to a cmsghdr structure which is constructed by
     this function and stored in the area of memory pointed to by bp.

     The type is either IPV6_HOPOPTS or IPV6_DSTOPTS and is stored in the
     cmsg_type member of the cmsghdr structure mentioned above.

inet6_option_append

     This function appends a Hop-by-Hop option or a Destination option into an
     ancillary data object previously initialized by a call to
     inet6_option_init(). The inet6_option_append() function returns 0 if it
     succeeds or -1 when an error occurs.

     The cmsg argument is a pointer to the cmsghdr structure that was initial-
     ized by a call to inet6_option_init().

     The typep argument is a pointer to the 8-bit option type. All options are
     encoded as type-length-value tuples and it is assumed that the typep
     field is immediately followed by the 8-bit option data length field,
     which is then followed by the option data.

     The option types of 0 and 1 are reserved for the Pad1 and PadN options
     respectively. All other values from 2 through 255 are available for ap-
     plications to use.

     The option data length, since it is stored in 8 bites, must have a value
     between 0 and 255, inclusive.

     The multx argument is the value x in the alignment term "xn + y" and in-
     dicates the byte alignment necessary for the data. Alignments may be
     specified as 1, 2, 4, or 8 bytes, which is no alignment, 16-bit, 32-bit
     and 64-bit alignments respectively.

     The plusy argument is the value y in the alignment term "xn + y" and must
     have a value between 0 and 7, inclusive, indicating the amount of padding
     that is necessary for an option.

inet6_option_alloc

     The inet6_option_alloc() function appends a Hop-by-Hop option or a Desti-
     nation option into an ancillary data object that has previously been ini-
     tialized by a call to inet6_option_init(). A successful call to the
     inet6_option_alloc() function returns a pointer to the 8-bit option type
     field, which is at the beginning of the allocated region.
     inet6_option_alloc() returns NULL when an error has occurred.

     The difference between the inet6_option_alloc() and inet6_option_append()
     functions is that the latter copies the contents of a previously built
     option into the ancillary data object while the former returns a pointer
     to the place in the data object where the option's TLV must then be built
     by the application.

     The cmsg argument is a pointer to a cmsghdr structure that was initial-
     ized by inet6_option_init().

     The datalen argument is the value of the option data length byte for this
     option. This value is required as an argument to allow the function to
     determine 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.)

     The multx and plusy arguments are identical to the arguments of the same
     name described in the inet6_option_init() function above.

inet6_option_next

     The inet6_option_next() function is used to process Hop-by-Hop and Desti-
     nation options that are present in an ancillary data object. When an op-
     tion remains to be processed, the return value of the inet6_option_next()
     function is 0 and the *tptrp argument points to the 8-bit option type
     field, which is followed by the 8-bit option data length, and then the
     option data. When no more options remain to be processed, the return
     value is -1 and *tptrp is NULL. When an error occurs, the return value is
     -1, but the *tptrp argument is not NULL. This set of return values allows
     a program to easily loop through all the options in an ancillary data ob-
     ject, checking for the error and end of stream conditions along the way.

     When a valid option is returned, the cmsg argument points to a cmsghdr
     where the cmsg_level element equals IPPROTO_IPV6 and the cmsg_type ele-
     ment is either IPV6_HOPOPTS or IPV6_DSTOPTS.

     The tptrp argument 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 ob-
     ject each time the function is called. When the inet6_option_next() func-
     tion is called for the first time on a given ancillary data object,
     *tptrp must be set to NULL.

     Each time the function returns success, the *tptrp argument points to the
     8-bit option type field for the next option to be processed.

inet6_option_find

     The inet6_option_find() function allows an application to search for a
     particular option type in an ancillary data object. The cmsg argument is
     a pointer to a cmsghdr structure in which the cmsg_level element equals
     IPPROTO_IPV6 and the cmsg_type element is either IPV6_HOPOPTS or
     IPV6_DSTOPTS.

     The tptrp argument is handled exactly as in the inet6_option_next() func-
     tion described above.

     The inet6_option_find() function starts searching for an option of the
     specified type beginning after the value of *tptrp.

EXAMPLES

     RFC 2292 gives comprehensive examples in chapter 6.

DIAGNOSTICS

     The inet6_option_init() and inet6_option_append() functions return 0 on
     success or -1 on an error.

     The inet6_option_alloc() function returns NULL on an error.

     When inet6_option_next() or inet6_option_find() detect an error they re-
     turn -1, setting *tptrp to a non NULL value.

SEE ALSO

     inet6(4), ip6(4)

     W. 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.

STANDARDS

     The functions are documented in "Advanced Sockets API for IPv6" (RFC
     2292).

HISTORY

     This implementation first appeared in the KAME advanced networking kit.

MirOS BSD #10-current         December 23, 2004                              2

Generated on 2014-04-02 20:57:59 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.