+++ /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_option_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="inet"
-HREF="net-common-tcpip-manpages-inet.html"><LINK
-REL="NEXT"
-TITLE="inet6_rthdr_space"
-HREF="net-common-tcpip-manpages-inet6-rthdr-space.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-inet.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-inet6-rthdr-space.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-OPTION-SPACE">inet6_option_space</H1
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
->INET6_OPTION_SPACE(3) System 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
-
-SYNOPSIS
- #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 constranints, 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
- option when it is stored as ancillary data, including the cmsghdr struc-
- ture 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 suc-
- cess 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 indi-
- vidual 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
- 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 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
- 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.
-
-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
- </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-inet.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-inet6-rthdr-space.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->inet</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"
->inet6_rthdr_space</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file