--- /dev/null
+<!-- Copyright (C) 2003 Red Hat, Inc. -->
+<!-- This material may be distributed only subject to the terms -->
+<!-- and conditions set forth in the Open Publication License, v1.0 -->
+<!-- or later (the latest version is presently available at -->
+<!-- http://www.opencontent.org/openpub/). -->
+<!-- Distribution of the work or derivative of the work in any -->
+<!-- standard (paper) book form is prohibited unless prior -->
+<!-- permission is obtained from the copyright holder. -->
+<HTML
+><HEAD
+><TITLE
+>inet6_rthdr_space</TITLE
+><meta name="MSSmartTagsPreventParsing" content="TRUE">
+<META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
+REL="HOME"
+TITLE="eCos Reference Manual"
+HREF="ecos-ref.html"><LINK
+REL="UP"
+TITLE="TCP/IP Library Reference"
+HREF="tcpip-library-reference.html"><LINK
+REL="PREVIOUS"
+TITLE="inet6_option_space"
+HREF="net-common-tcpip-manpages-inet6-option-space.html"><LINK
+REL="NEXT"
+TITLE="inet_net"
+HREF="net-common-tcpip-manpages-inet-net.html"></HEAD
+><BODY
+CLASS="SECT1"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+SUMMARY="Header navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>eCos Reference Manual</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="net-common-tcpip-manpages-inet6-option-space.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+>Chapter 38. TCP/IP Library Reference</TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="net-common-tcpip-manpages-inet-net.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECT1"
+><H1
+CLASS="SECT1"
+><A
+NAME="NET-COMMON-TCPIP-MANPAGES-INET6-RTHDR-SPACE">inet6_rthdr_space</H1
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>INET6_RTHDR_SPACE(3) System Library Functions Manual INET6_RTHDR_SPACE(3)
+
+NAME
+ inet6_rthdr_space, inet6_rthdr_init, inet6_rthdr_add,
+ inet6_rthdr_lasthop, inet6_rthdr_reverse, inet6_rthdr_segments,
+ inet6_rthdr_getaddr, inet6_rthdr_getflags - IPv6 Routing Header Options
+ manipulation
+
+SYNOPSIS
+ #include <netinet/in.h>
+
+ size_t
+ inet6_rthdr_space(int type, int segments);
+
+ struct cmsghdr *
+ inet6_rthdr_init(void *bp, int type);
+
+ int
+ inet6_rthdr_add(struct cmsghdr *cmsg, const struct in6_addr *addr,
+ unsigned int flags);
+
+ int
+ inet6_rthdr_lasthop(struct cmsghdr *cmsg, unsigned int flags);
+
+ int
+ inet6_rthdr_reverse(const struct cmsghdr *in, struct cmsghdr *out);
+
+ int
+ inet6_rthdr_segments(const struct cmsghdr *cmsg);
+
+ struct in6_addr *
+ inet6_rthdr_getaddr(struct cmsghdr *cmsg, int index);
+
+ int
+ inet6_rthdr_getflags(const struct cmsghdr *cmsg, int index);
+
+DESCRIPTION
+ RFC2292 IPv6 advanced API defines eight functions that the application
+ calls to build and examine a Routing header. Four functions build a
+ Routing header:
+
+ inet6_rthdr_space() return #bytes required for ancillary data
+
+ inet6_rthdr_init() initialize ancillary data for Routing header
+
+ inet6_rthdr_add() add IPv6 address & flags to Routing header
+
+ inet6_rthdr_lasthop() specify the flags for the final hop
+
+ Four functions deal with a returned Routing header:
+
+ inet6_rthdr_reverse() reverse a Routing header
+
+ inet6_rthdr_segments() return #segments in a Routing header
+
+ inet6_rthdr_getaddr() fetch one address from a Routing header
+
+ inet6_rthdr_getflags() fetch one flag from a Routing header
+
+ The function prototypes for these functions are all in the <netinet/in.h>
+ header.
+
+ inet6_rthdr_space
+ This function returns the number of bytes required to hold a Routing
+ header of the specified type containing the specified number of segments
+ (addresses). For an IPv6 Type 0 Routing header, the number of segments
+ must be between 1 and 23, inclusive. The return value includes the size
+ of the cmsghdr structure that precedes the Routing header, and any
+ required padding.
+
+ If the return value is 0, then either the type of the Routing header is
+ not supported by this implementation or the number of segments is invalid
+ for this type of Routing header.
+
+ Note: This function returns the size but does not allocate the space
+ required for the ancillary data. This allows an application to allocate
+ a larger buffer, if other ancillary data objects are desired, since all
+ the ancillary data objects must be specified to sendmsg(2) as a single
+ msg_control buffer.
+
+ inet6_rthdr_init
+ This function initializes the buffer pointed to by bp to contain a
+ cmsghdr structure followed by a Routing header of the specified type.
+ The cmsg_len member of the cmsghdr structure is initialized to the size
+ of the structure plus the amount of space required by the Routing header.
+ The cmsg_level and cmsg_type members are also initialized as required.
+
+ The caller must allocate the buffer and its size can be determined by
+ calling inet6_rthdr_space().
+
+ Upon success the return value is the pointer to the cmsghdr structure,
+ and this is then used as the first argument to the next two functions.
+ Upon an error the return value is NULL.
+
+ inet6_rthdr_add
+ This function adds the address pointed to by addr to the end of the Rout-
+ ing header being constructed and sets the type of this hop to the value
+ of flags. For an IPv6 Type 0 Routing header, flags must be either
+ IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.
+
+ If successful, the cmsg_len member of the cmsghdr structure is updated to
+ account for the new address in the Routing header and the return value of
+ the function is 0. Upon an error the return value of the function is -1.
+
+ inet6_rthdr_lasthop
+ This function specifies the Strict/Loose flag for the final hop of a
+ Routing header. For an IPv6 Type 0 Routing header, flags must be either
+ IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.
+
+ The return value of the function is 0 upon success, or -1 upon an error.
+
+ Notice that a Routing header specifying N intermediate nodes requires N+1
+ Strict/Loose flags. This requires N calls to inet6_rthdr_add() followed
+ by one call to inet6_rthdr_lasthop().
+
+ inet6_rthdr_reverse
+ This function takes a Routing header that was received as ancillary data
+ (pointed to by the first argument, in) and writes a new Routing header
+ that sends datagrams along the reverse of that route. Both arguments are
+ allowed to point to the same buffer (that is, the reversal can occur in
+ place).
+
+ The return value of the function is 0 on success, or -1 upon an error.
+
+ inet6_rthdr_segments
+ This function returns the number of segments (addresses) contained in the
+ Routing header described by cmsg. On success the return value is between
+ 1 and 23, inclusive. The return value of the function is -1 upon an
+ error.
+
+ inet6_rthdr_getaddr
+ This function returns a pointer to the IPv6 address specified by index
+ (which must have a value between 1 and the value returned by
+ inet6_rthdr_segments()) in the Routing header described by cmsg. An
+ application should first call inet6_rthdr_segments() to obtain the number
+ of segments in the Routing header.
+
+ Upon an error the return value of the function is NULL.
+
+ inet6_rthdr_getflags
+ This function returns the flags value specified by index (which must have
+ a value between 0 and the value returned by inet6_rthdr_segments()) in
+ the Routing header described by cmsg. For an IPv6 Type 0 Routing header
+ the return value will be either IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.
+
+ Upon an error the return value of the function is -1.
+
+ Note: Addresses are indexed starting at 1, and flags starting at 0, to
+ maintain consistency with the terminology and figures in RFC2460.
+
+DIAGNOSTICS
+ inet6_rthdr_space() returns 0 on errors.
+
+ inet6_rthdr_add(), inet6_rthdr_lasthop() and inet6_rthdr_reverse() return
+ 0 on success, and returns -1 on error.
+
+ inet6_rthdr_init() and inet6_rthdr_getaddr() return NULL on error.
+
+ inet6_rthdr_segments() and inet6_rthdr_getflags() return -1 on error.
+
+EXAMPLES
+ RFC2292 gives comprehensive examples in chapter 8.
+
+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.
+
+ inet6_rthdr_reverse() is not implemented yet.
+
+BSD December 10, 1999 BSD
+ </PRE
+></TD
+></TR
+></TABLE
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="net-common-tcpip-manpages-inet6-option-space.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="ecos-ref.html"
+ACCESSKEY="H"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="net-common-tcpip-manpages-inet-net.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>inet6_option_space</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="tcpip-library-reference.html"
+ACCESSKEY="U"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>inet_net</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file