Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
INET6_OPTION_SPACE(3)	 BSD Library Functions 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 Options manipulation

LIBRARY
     Standard C	Library	(libc, -lc)

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
     Building and parsing the Hop-by-Hop and Destination options is compli-
     cated due to alignment constraints, padding and ancillary data manipula-
     tion.  RFC2292 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 op-
     tion when it is stored as ancillary data, including the cmsghdr structure
     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 defining the op-
     tion, 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 op-
     tion 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 little
     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	suc-
     cess or -1	on an error.

     bp	is a pointer to	previously allocated space that	will contain the an-
     cillary data object.  It must be large enough to contain all the individ-
     ual 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	ini-
     tialized 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 initial-
     ized 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	ini-
     tializes these three fields (the type-length-value, or TLV) before	call-
     ing 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 an-
     cillary 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 initial-
     ized 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 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.)

     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 processed,
     the return	value of the function is 0 and *tptrp points to	the 8-bit op-
     tion type field (which is followed	by the 8-bit option data length, fol-
     lowed 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 re-
     turn 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 op-
     tion 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 an-
     cillary 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 oc-
     curs, the return value is -1 and *tptrp is	not NULL.

DIAGNOSTICS
     inet6_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.

EXAMPLES
     RFC2292 gives comprehensive examples in chapter 6.

SEE ALSO
     W.	Stevens	and M. Thomas, Advanced	Sockets	API for	IPv6, RFC2292,
     February 1998.

     S.	Deering	and R. Hinden, Internet	Protocol, Version 6 (IPv6)
     Specification, RFC2460, December 1998.

HISTORY
     The implementation	first appeared in KAME advanced	networking kit.

STANDARDS
     The functions are documented in "Advanced Sockets API for IPv6"
     (RFC2292).

BUGS
     The text was shamelessly copied from RFC2292.

BSD			       December	10, 1999			   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | DIAGNOSTICS | EXAMPLES | SEE ALSO | HISTORY | STANDARDS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=inet6_option_space&sektion=3&manpath=FreeBSD+4.9-RELEASE>

home | help