doc/html/ref/net-common-tcpip-manpages-inet6-rthdr-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_rthdr_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="inet6_option_space"
  26 HREF="net-common-tcpip-manpages-inet6-option-space.html"><LINK
  27 REL="NEXT"
  28 TITLE="inet_net"
  29 HREF="net-common-tcpip-manpages-inet-net.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-inet6-option-space.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-inet-net.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-RTHDR-SPACE">inet6_rthdr_space</H1
  86 ><TABLE
  87 BORDER="5"
  88 BGCOLOR="#E0E0F0"
  89 WIDTH="70%"
  90 ><TR
  91 ><TD
  92 ><PRE
  93 CLASS="SCREEN"
  94 >INET6_RTHDR_SPACE(3)    System Library Functions Manual   INET6_RTHDR_SPACE(3)
  95
  96 NAME
  97      inet6_rthdr_space, inet6_rthdr_init, inet6_rthdr_add,
  98      inet6_rthdr_lasthop, inet6_rthdr_reverse, inet6_rthdr_segments,
  99      inet6_rthdr_getaddr, inet6_rthdr_getflags - IPv6 Routing Header Options
 100      manipulation
 101
 102 SYNOPSIS
 103      #include &lt;netinet/in.h&#62;
 104
 105      size_t
 106      inet6_rthdr_space(int type, int segments);
 107
 108      struct cmsghdr *
 109      inet6_rthdr_init(void *bp, int type);
 110
 111      int
 112      inet6_rthdr_add(struct cmsghdr *cmsg, const struct in6_addr *addr,
 113              unsigned int flags);
 114
 115      int
 116      inet6_rthdr_lasthop(struct cmsghdr *cmsg, unsigned int flags);
 117
 118      int
 119      inet6_rthdr_reverse(const struct cmsghdr *in, struct cmsghdr *out);
 120
 121      int
 122      inet6_rthdr_segments(const struct cmsghdr *cmsg);
 123
 124      struct in6_addr *
 125      inet6_rthdr_getaddr(struct cmsghdr *cmsg, int index);
 126
 127      int
 128      inet6_rthdr_getflags(const struct cmsghdr *cmsg, int index);
 129
 130 DESCRIPTION
 131      RFC2292 IPv6 advanced API defines eight functions that the application
 132      calls to build and examine a Routing header.  Four functions build a
 133      Routing header:
 134
 135      inet6_rthdr_space() return #bytes required for ancillary data
 136
 137      inet6_rthdr_init() initialize ancillary data for Routing header
 138
 139      inet6_rthdr_add() add IPv6 address &amp; flags to Routing header
 140
 141      inet6_rthdr_lasthop() specify the flags for the final hop
 142
 143      Four functions deal with a returned Routing header:
 144
 145      inet6_rthdr_reverse() reverse a Routing header
 146
 147      inet6_rthdr_segments() return #segments in a Routing header
 148
 149      inet6_rthdr_getaddr() fetch one address from a Routing header
 150
 151      inet6_rthdr_getflags() fetch one flag from a Routing header
 152
 153      The function prototypes for these functions are all in the &lt;netinet/in.h&#62;
 154      header.
 155
 156    inet6_rthdr_space
 157      This function returns the number of bytes required to hold a Routing
 158      header of the specified type containing the specified number of segments
 159      (addresses).  For an IPv6 Type 0 Routing header, the number of segments
 160      must be between 1 and 23, inclusive.  The return value includes the size
 161      of the cmsghdr structure that precedes the Routing header, and any
 162      required padding.
 163
 164      If the return value is 0, then either the type of the Routing header is
 165      not supported by this implementation or the number of segments is invalid
 166      for this type of Routing header.
 167
 168      Note: This function returns the size but does not allocate the space
 169      required for the ancillary data.  This allows an application to allocate
 170      a larger buffer, if other ancillary data objects are desired, since all
 171      the ancillary data objects must be specified to sendmsg(2) as a single
 172      msg_control buffer.
 173
 174    inet6_rthdr_init
 175      This function initializes the buffer pointed to by bp to contain a
 176      cmsghdr structure followed by a Routing header of the specified type.
 177      The cmsg_len member of the cmsghdr structure is initialized to the size
 178      of the structure plus the amount of space required by the Routing header.
 179      The cmsg_level and cmsg_type members are also initialized as required.
 180
 181      The caller must allocate the buffer and its size can be determined by
 182      calling inet6_rthdr_space().
 183
 184      Upon success the return value is the pointer to the cmsghdr structure,
 185      and this is then used as the first argument to the next two functions.
 186      Upon an error the return value is NULL.
 187
 188    inet6_rthdr_add
 189      This function adds the address pointed to by addr to the end of the Rout-
 190      ing header being constructed and sets the type of this hop to the value
 191      of flags.  For an IPv6 Type 0 Routing header, flags must be either
 192      IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.
 193
 194      If successful, the cmsg_len member of the cmsghdr structure is updated to
 195      account for the new address in the Routing header and the return value of
 196      the function is 0.  Upon an error the return value of the function is -1.
 197
 198    inet6_rthdr_lasthop
 199      This function specifies the Strict/Loose flag for the final hop of a
 200      Routing header.  For an IPv6 Type 0 Routing header, flags must be either
 201      IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.
 202
 203      The return value of the function is 0 upon success, or -1 upon an error.
 204
 205      Notice that a Routing header specifying N intermediate nodes requires N+1
 206      Strict/Loose flags.  This requires N calls to inet6_rthdr_add() followed
 207      by one call to inet6_rthdr_lasthop().
 208
 209    inet6_rthdr_reverse
 210      This function takes a Routing header that was received as ancillary data
 211      (pointed to by the first argument, in) and writes a new Routing header
 212      that sends datagrams along the reverse of that route.  Both arguments are
 213      allowed to point to the same buffer (that is, the reversal can occur in
 214      place).
 215
 216      The return value of the function is 0 on success, or -1 upon an error.
 217
 218    inet6_rthdr_segments
 219      This function returns the number of segments (addresses) contained in the
 220      Routing header described by cmsg.  On success the return value is between
 221      1 and 23, inclusive.  The return value of the function is -1 upon an
 222      error.
 223
 224    inet6_rthdr_getaddr
 225      This function returns a pointer to the IPv6 address specified by index
 226      (which must have a value between 1 and the value returned by
 227      inet6_rthdr_segments()) in the Routing header described by cmsg.  An
 228      application should first call inet6_rthdr_segments() to obtain the number
 229      of segments in the Routing header.
 230
 231      Upon an error the return value of the function is NULL.
 232
 233    inet6_rthdr_getflags
 234      This function returns the flags value specified by index (which must have
 235      a value between 0 and the value returned by inet6_rthdr_segments()) in
 236      the Routing header described by cmsg.  For an IPv6 Type 0 Routing header
 237      the return value will be either IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.
 238
 239      Upon an error the return value of the function is -1.
 240
 241      Note: Addresses are indexed starting at 1, and flags starting at 0, to
 242      maintain consistency with the terminology and figures in RFC2460.
 243
 244 DIAGNOSTICS
 245      inet6_rthdr_space() returns 0 on errors.
 246
 247      inet6_rthdr_add(), inet6_rthdr_lasthop() and inet6_rthdr_reverse() return
 248      0 on success, and returns -1 on error.
 249
 250      inet6_rthdr_init() and inet6_rthdr_getaddr() return NULL on error.
 251
 252      inet6_rthdr_segments() and inet6_rthdr_getflags() return -1 on error.
 253
 254 EXAMPLES
 255      RFC2292 gives comprehensive examples in chapter 8.
 256
 257 SEE ALSO
 258      W. Stevens and M. Thomas, Advanced Sockets API for IPv6, RFC2292,
 259      February 1998.
 260
 261      S. Deering and R. Hinden, Internet Protocol, Version 6 (IPv6)
 262      Specification, RFC2460, December 1998.
 263
 264 HISTORY
 265      The implementation first appeared in KAME advanced networking kit.
 266
 267 STANDARDS
 268      The functions are documented in ``Advanced Sockets API for IPv6''
 269      (RFC2292).
 270
 271 BUGS
 272      The text was shamelessly copied from RFC2292.
 273
 274      inet6_rthdr_reverse() is not implemented yet.
 275
 276 BSD                            December 10, 1999                           BSD
 277     </PRE
 278 ></TD
 279 ></TR
 280 ></TABLE
 281 ></DIV
 282 ><DIV
 283 CLASS="NAVFOOTER"
 284 ><HR
 285 ALIGN="LEFT"
 286 WIDTH="100%"><TABLE
 287 SUMMARY="Footer navigation table"
 288 WIDTH="100%"
 289 BORDER="0"
 290 CELLPADDING="0"
 291 CELLSPACING="0"
 292 ><TR
 293 ><TD
 294 WIDTH="33%"
 295 ALIGN="left"
 296 VALIGN="top"
 297 ><A
 298 HREF="net-common-tcpip-manpages-inet6-option-space.html"
 299 ACCESSKEY="P"
 300 >Prev</A
 301 ></TD
 302 ><TD
 303 WIDTH="34%"
 304 ALIGN="center"
 305 VALIGN="top"
 306 ><A
 307 HREF="ecos-ref.html"
 308 ACCESSKEY="H"
 309 >Home</A
 310 ></TD
 311 ><TD
 312 WIDTH="33%"
 313 ALIGN="right"
 314 VALIGN="top"
 315 ><A
 316 HREF="net-common-tcpip-manpages-inet-net.html"
 317 ACCESSKEY="N"
 318 >Next</A
 319 ></TD
 320 ></TR
 321 ><TR
 322 ><TD
 323 WIDTH="33%"
 324 ALIGN="left"
 325 VALIGN="top"
 326 >inet6_option_space</TD
 327 ><TD
 328 WIDTH="34%"
 329 ALIGN="center"
 330 VALIGN="top"
 331 ><A
 332 HREF="tcpip-library-reference.html"
 333 ACCESSKEY="U"
 334 >Up</A
 335 ></TD
 336 ><TD
 337 WIDTH="33%"
 338 ALIGN="right"
 339 VALIGN="top"
 340 >inet_net</TD
 341 ></TR
 342 ></TABLE
 343 ></DIV
 344 ></BODY
 345 ></HTML
 346 >