.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" $Id: inet6_rthdr_space.3,v 1.2 2002/03/19 17:20:07 majka Exp $
+.\" $Id: inet6_rthdr_space.3,v 1.3 2005/01/19 00:30:03 majka Exp $
.\" $FreeBSD: src/lib/libc/net/inet6_rthdr_space.3,v 1.1.2.5 2001/08/17 15:42:38 ru Exp $
.\"
.Dd December 10, 1999
The function prototypes for these functions are all in the
.Aq Li netinet/in.h
header.
-.\"
-.Ss inet6_rthdr_space
-This function returns the number of bytes required to hold a Routing
-header of the specified
-.Fa type
-containing the specified number of
-.Fa 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.
-.Pp
-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.
-.Pp
-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
-.Xr sendmsg 2
-as a single
-.Li msg_control
-buffer.
-.\"
-.Ss inet6_rthdr_init
-This function initializes the buffer pointed to by
-.Fa bp
-to contain a
-.Li cmsghdr
-structure followed by a Routing header of the specified
-.Fa type .
-The
-.Li cmsg_len
-member of the
-.Li cmsghdr
-structure is initialized to the
-size of the structure plus the amount of space required by the
-Routing header.
-The
-.Li cmsg_level
-and
-.Li cmsg_type
-members are also initialized as required.
-.Pp
-The caller must allocate the buffer and its size can be determined by
-calling
-.Fn inet6_rthdr_space .
-.Pp
-Upon success the return value is the pointer to the
-.Li cmsghdr
-structure, and this is then used as the first argument to the next
-two functions.
-Upon an error the return value is
-.Dv NULL .
-.\"
-.Ss inet6_rthdr_add
-This function adds the address pointed to by
-.Fa addr
-to the end of the
-Routing header being constructed and sets the type of this hop to the
-value of
-.Fa flags .
-For an IPv6 Type 0 Routing header,
-.Fa flags
-must be
-either
-.Dv IPV6_RTHDR_LOOSE
-or
-.Dv IPV6_RTHDR_STRICT .
-.Pp
-If successful, the
-.Li cmsg_len
-member of the
-.Li 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.
-.\"
-.Ss 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,
-.Fa flags
-must be either
-.Dv IPV6_RTHDR_LOOSE
-or
-.Dv IPV6_RTHDR_STRICT .
-.Pp
-The return value of the function is 0 upon success, or -1 upon an error.
-.Pp
-Notice that a Routing header specifying
-.Li N
-intermediate nodes requires
-.Li N+1
-Strict/Loose flags.
-This requires
-.Li N
-calls to
-.Fn inet6_rthdr_add
-followed by one call to
-.Fn inet6_rthdr_lasthop .
-.\"
-.Ss inet6_rthdr_reverse
-This function is not yet implemented.
-When implemented, this should behave as follows.
-.Pp
-This function takes a Routing header that was received as ancillary
-data
-(pointed to by the first argument,
-.Fa 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).
-.Pp
-The return value of the function is 0 on success, or -1 upon an
-error.
-.\"
-.Ss inet6_rthdr_segments
-This function returns the number of segments
-(addresses)
-contained in
-the Routing header described by
-.Fa cmsg .
-On success the return value is
-between 1 and 23, inclusive.
-The return value of the function is -1 upon an error.
-.\"
-.Ss inet6_rthdr_getaddr
-This function returns a pointer to the IPv6 address specified by
-.Fa index
-(which must have a value between 1 and the value returned by
-.Fn inet6_rthdr_segments )
-in the Routing header described by
-.Fa cmsg .
-An
-application should first call
-.Fn inet6_rthdr_segments
-to obtain the number of segments in the Routing header.
-.Pp
-Upon an error the return value of the function is
-.Dv NULL .
-.\"
-.Ss inet6_rthdr_getflags
-This function returns the flags value specified by
-.Fa index
-(which must
-have a value between 0 and the value returned by
-.Fn inet6_rthdr_segments )
-in the Routing header described by
-.Fa cmsg .
-For an IPv6 Type 0 Routing header the return value will be either
-.Dv IPV6_RTHDR_LOOSE
-or
-.Dv IPV6_RTHDR_STRICT .
-.Pp
-Upon an error the return value of the function is -1.
.Pp
-Note: Addresses are indexed starting at 1, and flags starting at 0,
-to maintain consistency with the terminology and figures in RFC2460.
+The full description of these functions is available in RFC2292.
.\"
.Sh DIAGNOSTICS
.Fn inet6_rthdr_space
projects / apple / libinfo.git / blobdiff