*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> inet6_option_find (3)              
Title
Content
Arch
Section
 

ET6_OPTION_SPACE(3)

Contents


IN

NAME    [Toc]    [Back]

     inet6_option_space, inet6_option_init, inet6_option_append,
     inet6_option_alloc, inet6_option_next,  inet6_option_find  -
IPv6 Hop-byHop
 and Destination Options manipulation

SYNOPSIS    [Toc]    [Back]

     #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    [Toc]    [Back]

     Building and parsing the Hop-by-Hop and Destination  options
is complicated
  due to alignment constraints, padding and ancillary data
manipulation.
     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 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 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 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 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 individual
   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 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 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.

EXAMPLES    [Toc]    [Back]

     RFC 2292 gives comprehensive examples in chapter 6.

DIAGNOSTICS    [Toc]    [Back]

     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.

SEE ALSO    [Toc]    [Back]

      
      
     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    [Toc]    [Back]

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

HISTORY    [Toc]    [Back]

     The  implementation first appeared in KAME advanced networking kit.

BUGS    [Toc]    [Back]

     The text was shamelessly copied from RFC 2292.

OpenBSD     3.6                        December     10,      1999
[ Back ]
 Similar pages
Name OS Title
inet6_opt_set_val FreeBSD IPv6 Hop-by-Hop and Destination Options manipulation
inet6_opt_find FreeBSD IPv6 Hop-by-Hop and Destination Options manipulation
inet6_opt_init FreeBSD IPv6 Hop-by-Hop and Destination Options manipulation
inet6_opt_append FreeBSD IPv6 Hop-by-Hop and Destination Options manipulation
inet6_opt_next FreeBSD IPv6 Hop-by-Hop and Destination Options manipulation
inet6_opt_get_val FreeBSD IPv6 Hop-by-Hop and Destination Options manipulation
inet6_opt_finish FreeBSD IPv6 Hop-by-Hop and Destination Options manipulation
inet6_rthdr_lasthop NetBSD IPv6 Routing Header Options manipulation
inet6_rthdr_add OpenBSD IPv6 Routing Header Options manipulation
inet6_rthdr_reverse NetBSD IPv6 Routing Header Options manipulation
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service