doc/html/ref/net-common-tcpip-manpages-inet6-option-space.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >inet6_option_space</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="TCP/IP Library Reference"
  23 HREF="tcpip-library-reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="inet"
  26 HREF="net-common-tcpip-manpages-inet.html"><LINK
  27 REL="NEXT"
  28 TITLE="inet6_rthdr_space"
  29 HREF="net-common-tcpip-manpages-inet6-rthdr-space.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="net-common-tcpip-manpages-inet.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 38. TCP/IP Library Reference</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="net-common-tcpip-manpages-inet6-rthdr-space.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="NET-COMMON-TCPIP-MANPAGES-INET6-OPTION-SPACE">inet6_option_space</H1
  86 ><TABLE
  87 BORDER="5"
  88 BGCOLOR="#E0E0F0"
  89 WIDTH="70%"
  90 ><TR
  91 ><TD
  92 ><PRE
  93 CLASS="SCREEN"
  94 >INET6_OPTION_SPACE(3)   System Library Functions Manual  INET6_OPTION_SPACE(3)
  95
  96 NAME
  97      inet6_option_space, inet6_option_init, inet6_option_append,
  98      inet6_option_alloc, inet6_option_next, inet6_option_find - IPv6 Hop-by-
  99      Hop and Destination Options manipulation
 100
 101 SYNOPSIS
 102      #include &lt;netinet/in.h&#62;
 103
 104      int
 105      inet6_option_space(int nbytes);
 106
 107      int
 108      inet6_option_init(void *bp, struct cmsghdr **cmsgp, int type);
 109
 110      int
 111      inet6_option_append(struct cmsghdr *cmsg, const u_int8_t *typep,
 112              int multx, int plusy);
 113
 114      u_int8_t *
 115      inet6_option_alloc(struct cmsghdr *cmsg, int datalen, int multx,
 116              int plusy);;
 117
 118      int
 119      inet6_option_next(const struct cmsghdr *cmsg, u_int8_t **tptrp);
 120
 121      int
 122      inet6_option_find(const struct cmsghdr *cmsg, u_int8_t **tptrp,
 123              int type);
 124
 125 DESCRIPTION
 126      Building and parsing the Hop-by-Hop and Destination options is compli-
 127      cated due to alignment constranints, padding and ancillary data manipula-
 128      tion.  RFC2292 defines a set of functions to help the application.  The
 129      function prototypes for these functions are all in the &lt;netinet/in.h&#62;
 130      header.
 131
 132    inet6_option_space
 133      inet6_option_space() returns the number of bytes required to hold an
 134      option when it is stored as ancillary data, including the cmsghdr struc-
 135      ture at the beginning, and any padding at the end (to make its size a
 136      multiple of 8 bytes).  The argument is the size of the structure defining
 137      the option, which must include any pad bytes at the beginning (the value
 138      y in the alignment term ``xn + y''), the type byte, the length byte, and
 139      the option data.
 140
 141      Note: If multiple options are stored in a single ancillary data object,
 142      which is the recommended technique, this function overestimates the
 143      amount of space required by the size of N-1 cmsghdr structures, where N
 144      is the number of options to be stored in the object.  This is of little
 145      consequence, since it is assumed that most Hop-by-Hop option headers and
 146      Destination option headers carry only one option (appendix B of
 147      [RFC-2460]).
 148
 149    inet6_option_init
 150      inet6_option_init() is called once per ancillary data object that will
 151      contain either Hop-by-Hop or Destination options.  It returns 0 on suc-
 152      cess or -1 on an error.
 153
 154      bp is a pointer to previously allocated space that will contain the
 155      ancillary data object.  It must be large enough to contain all the indi-
 156      vidual options to be added by later calls to inet6_option_append() and
 157      inet6_option_alloc().
 158
 159      cmsgp is a pointer to a pointer to a cmsghdr structure.  *cmsgp is ini-
 160      tialized by this function to point to the cmsghdr structure constructed
 161      by this function in the buffer pointed to by bp.
 162
 163      type is either IPV6_HOPOPTS or IPV6_DSTOPTS.  This type is stored in the
 164      cmsg_type member of the cmsghdr structure pointed to by *cmsgp.
 165
 166    inet6_option_append
 167      This function appends a Hop-by-Hop option or a Destination option into an
 168      ancillary data object that has been initialized by inet6_option_init().
 169      This function returns 0 if it succeeds or -1 on an error.
 170
 171      cmsg is a pointer to the cmsghdr structure that must have been initial-
 172      ized by inet6_option_init().
 173
 174      typep is a pointer to the 8-bit option type.  It is assumed that this
 175      field is immediately followed by the 8-bit option data length field,
 176      which is then followed immediately by the option data.  The caller ini-
 177      tializes these three fields (the type-length-value, or TLV) before call-
 178      ing this function.
 179
 180      The option type must have a value from 2 to 255, inclusive.  (0 and 1 are
 181      reserved for the Pad1 and PadN options, respectively.)
 182
 183      The option data length must have a value between 0 and 255, inclusive,
 184      and is the length of the option data that follows.
 185
 186      multx is the value x in the alignment term ``xn + y''.  It must have a
 187      value of 1, 2, 4, or 8.
 188
 189      plusy is the value y in the alignment term ``xn + y''.  It must have a
 190      value between 0 and 7, inclusive.
 191
 192    inet6_option_alloc
 193      This function appends a Hop-by-Hop option or a Destination option into an
 194      ancillary data object that has been initialized by inet6_option_init().
 195      This function returns a pointer to the 8-bit option type field that
 196      starts the option on success, or NULL on an error.
 197
 198      The difference between this function and inet6_option_append() is that
 199      the latter copies the contents of a previously built option into the
 200      ancillary data object while the current function returns a pointer to the
 201      space in the data object where the option's TLV must then be built by the
 202      caller.
 203
 204      cmsg is a pointer to the cmsghdr structure that must have been initial-
 205      ized by inet6_option_init().
 206
 207      datalen is the value of the option data length byte for this option.
 208      This value is required as an argument to allow the function to determine
 209      if padding must be appended at the end of the option.  (The
 210      inet6_option_append() function does not need a data length argument since
 211      the option data length must already be stored by the caller.)
 212
 213      multx is the value x in the alignment term ``xn + y''.  It must have a
 214      value of 1, 2, 4, or 8.
 215
 216      plusy is the value y in the alignment term ``xn + y''.  It must have a
 217      value between 0 and 7, inclusive.
 218
 219    inet6_option_next
 220      This function processes the next Hop-by-Hop option or Destination option
 221      in an ancillary data object.  If another option remains to be processed,
 222      the return value of the function is 0 and *tptrp points to the 8-bit
 223      option type field (which is followed by the 8-bit option data length,
 224      followed by the option data).  If no more options remain to be processed,
 225      the return value is -1 and *tptrp is NULL.  If an error occurs, the
 226      return value is -1 and *tptrp is not NULL.
 227
 228      cmsg is a pointer to cmsghdr structure of which cmsg_level equals
 229      IPPROTO_IPV6 and cmsg_type equals either IPV6_HOPOPTS or IPV6_DSTOPTS.
 230
 231      tptrp is a pointer to a pointer to an 8-bit byte and *tptrp is used by
 232      the function to remember its place in the ancillary data object each time
 233      the function is called.  The first time this function is called for a
 234      given ancillary data object, *tptrp must be set to NULL.
 235
 236      Each time this function returns success, *tptrp points to the 8-bit
 237      option type field for the next option to be processed.
 238
 239    inet6_option_find
 240      This function is similar to the previously described inet6_option_next()
 241      function, except this function lets the caller specify the option type to
 242      be searched for, instead of always returning the next option in the
 243      ancillary data object.  cmsg is a pointer to cmsghdr structure of which
 244      cmsg_level equals IPPROTO_IPV6 and cmsg_type equals either IPV6_HOPOPTS
 245      or IPV6_DSTOPTS.
 246
 247      tptrp is a pointer to a pointer to an 8-bit byte and *tptrp is used by
 248      the function to remember its place in the ancillary data object each time
 249      the function is called.  The first time this function is called for a
 250      given ancillary data object, *tptrp must be set to NULL.  ~ This function
 251      starts searching for an option of the specified type beginning after the
 252      value of *tptrp.  If an option of the specified type is located, this
 253      function returns 0 and *tptrp points to the 8- bit option type field for
 254      the option of the specified type.  If an option of the specified type is
 255      not located, the return value is -1 and *tptrp is NULL.  If an error
 256      occurs, the return value is -1 and *tptrp is not NULL.
 257
 258 DIAGNOSTICS
 259      inet6_option_init() and inet6_option_append() return 0 on success or -1
 260      on an error.
 261
 262      inet6_option_alloc() returns NULL on an error.
 263
 264      On errors, inet6_option_next() and inet6_option_find() return -1 setting
 265      *tptrp to non NULL value.
 266
 267 EXAMPLES
 268      RFC2292 gives comprehensive examples in chapter 6.
 269
 270 SEE ALSO
 271      W. Stevens and M. Thomas, Advanced Sockets API for IPv6, RFC2292,
 272      February 1998.
 273
 274      S. Deering and R. Hinden, Internet Protocol, Version 6 (IPv6)
 275      Specification, RFC2460, December 1998.
 276
 277 HISTORY
 278      The implementation first appeared in KAME advanced networking kit.
 279
 280 STANDARDS
 281      The functions are documented in ``Advanced Sockets API for IPv6''
 282      (RFC2292).
 283
 284 BUGS
 285      The text was shamelessly copied from RFC2292.
 286
 287 BSD                            December 10, 1999                           BSD
 288     </PRE
 289 ></TD
 290 ></TR
 291 ></TABLE
 292 ></DIV
 293 ><DIV
 294 CLASS="NAVFOOTER"
 295 ><HR
 296 ALIGN="LEFT"
 297 WIDTH="100%"><TABLE
 298 SUMMARY="Footer navigation table"
 299 WIDTH="100%"
 300 BORDER="0"
 301 CELLPADDING="0"
 302 CELLSPACING="0"
 303 ><TR
 304 ><TD
 305 WIDTH="33%"
 306 ALIGN="left"
 307 VALIGN="top"
 308 ><A
 309 HREF="net-common-tcpip-manpages-inet.html"
 310 ACCESSKEY="P"
 311 >Prev</A
 312 ></TD
 313 ><TD
 314 WIDTH="34%"
 315 ALIGN="center"
 316 VALIGN="top"
 317 ><A
 318 HREF="ecos-ref.html"
 319 ACCESSKEY="H"
 320 >Home</A
 321 ></TD
 322 ><TD
 323 WIDTH="33%"
 324 ALIGN="right"
 325 VALIGN="top"
 326 ><A
 327 HREF="net-common-tcpip-manpages-inet6-rthdr-space.html"
 328 ACCESSKEY="N"
 329 >Next</A
 330 ></TD
 331 ></TR
 332 ><TR
 333 ><TD
 334 WIDTH="33%"
 335 ALIGN="left"
 336 VALIGN="top"
 337 >inet</TD
 338 ><TD
 339 WIDTH="34%"
 340 ALIGN="center"
 341 VALIGN="top"
 342 ><A
 343 HREF="tcpip-library-reference.html"
 344 ACCESSKEY="U"
 345 >Up</A
 346 ></TD
 347 ><TD
 348 WIDTH="33%"
 349 ALIGN="right"
 350 VALIGN="top"
 351 >inet6_rthdr_space</TD
 352 ></TR
 353 ></TABLE
 354 ></DIV
 355 ></BODY
 356 ></HTML
 357 >