[BACK]Return to inet6_rthdr_space.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / inet

Annotation of src/lib/libc/inet/inet6_rthdr_space.3, Revision 1.3

1.3     ! wiz         1: .\"    $NetBSD: inet6_rthdr_space.3,v 1.2 2010/03/22 19:30:54 joerg Exp $
1.1       christos    2: .\"    $KAME: inet6_rthdr_space.3,v 1.8 2000/05/17 14:30:15 itojun Exp $
                      3: .\"
                      4: .\" Copyright (c) 1983, 1987, 1991, 1993
                      5: .\"    The Regents of the University of California.  All rights reserved.
                      6: .\"
                      7: .\" Redistribution and use in source and binary forms, with or without
                      8: .\" modification, are permitted provided that the following conditions
                      9: .\" are met:
                     10: .\" 1. Redistributions of source code must retain the above copyright
                     11: .\"    notice, this list of conditions and the following disclaimer.
                     12: .\" 2. Redistributions in binary form must reproduce the above copyright
                     13: .\"    notice, this list of conditions and the following disclaimer in the
                     14: .\"    documentation and/or other materials provided with the distribution.
                     15: .\" 3. Neither the name of the University nor the names of its contributors
                     16: .\"    may be used to endorse or promote products derived from this software
                     17: .\"    without specific prior written permission.
                     18: .\"
                     19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     22: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     29: .\" SUCH DAMAGE.
                     30: .\"
                     31: .Dd December 10, 1999
                     32: .Dt INET6_RTHDR_SPACE 3
                     33: .Os
                     34: .\"
                     35: .Sh NAME
                     36: .Nm inet6_rthdr_space ,
                     37: .Nm inet6_rthdr_init ,
                     38: .Nm inet6_rthdr_add ,
                     39: .Nm inet6_rthdr_lasthop ,
                     40: .Nm inet6_rthdr_reverse ,
                     41: .Nm inet6_rthdr_segments ,
                     42: .Nm inet6_rthdr_getaddr ,
                     43: .Nm inet6_rthdr_getflags
                     44: .Nd IPv6 Routing Header Options manipulation
                     45: .\"
                     46: .Sh SYNOPSIS
                     47: .In netinet/in.h
                     48: .Ft size_t
                     49: .Fn inet6_rthdr_space "int type" "int segments"
                     50: .Ft "struct cmsghdr *"
                     51: .Fn inet6_rthdr_init "void *bp" "int type"
                     52: .Ft int
                     53: .Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags"
                     54: .Ft int
                     55: .Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags"
                     56: .Ft int
                     57: .Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out"
                     58: .Ft int
                     59: .Fn inet6_rthdr_segments "const struct cmsghdr *cmsg"
                     60: .Ft "struct in6_addr *"
                     61: .Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index"
                     62: .Ft int
                     63: .Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index"
                     64: .\"
                     65: .Sh DESCRIPTION
                     66: RFC 2292 IPv6 advanced API defines eight
                     67: functions that the application calls to build and examine a Routing
                     68: header.
                     69: Four functions build a Routing header:
                     70: .Bl -hang
                     71: .It Fn inet6_rthdr_space
                     72: return #bytes required for ancillary data
                     73: .It Fn inet6_rthdr_init
                     74: initialize ancillary data for Routing header
                     75: .It Fn inet6_rthdr_add
1.3     ! wiz        76: add IPv6 address & flags to Routing header
1.1       christos   77: .It Fn inet6_rthdr_lasthop
                     78: specify the flags for the final hop
                     79: .El
                     80: .Pp
                     81: Four functions deal with a returned Routing header:
                     82: .Bl -hang
                     83: .It Fn inet6_rthdr_reverse
                     84: reverse a Routing header
                     85: .It Fn inet6_rthdr_segments
                     86: return #segments in a Routing header
                     87: .It Fn inet6_rthdr_getaddr
                     88: fetch one address from a Routing header
                     89: .It Fn inet6_rthdr_getflags
                     90: fetch one flag from a Routing header
                     91: .El
                     92: .Pp
                     93: The function prototypes for these functions are all in the
1.2       joerg      94: .In netinet/in.h
1.1       christos   95: header.
                     96: .\"
                     97: .Ss inet6_rthdr_space
                     98: This function returns the number of bytes required to hold a Routing
                     99: header of the specified
                    100: .Fa type
                    101: containing the specified number of
                    102: .Fa segments
                    103: .Pq addresses .
                    104: For an IPv6 Type 0 Routing header, the number
                    105: of segments must be between 1 and 23, inclusive.
                    106: The return value
                    107: includes the size of the cmsghdr structure that precedes the Routing
                    108: header, and any required padding.
                    109: .Pp
                    110: If the return value is 0, then either the type of the Routing header
                    111: is not supported by this implementation or the number of segments is
                    112: invalid for this type of Routing header.
                    113: .Pp
                    114: Note: This function returns the size but does not allocate the space
                    115: required for the ancillary data.
                    116: This allows an application to
                    117: allocate a larger buffer, if other ancillary data objects are
                    118: desired, since all the ancillary data objects must be specified to
                    119: .Xr sendmsg 2
                    120: as a single
                    121: .Li msg_control
                    122: buffer.
                    123: .\"
                    124: .Ss inet6_rthdr_init
                    125: This function initializes the buffer pointed to by
                    126: .Fa bp
                    127: to contain a
                    128: .Li cmsghdr
                    129: structure followed by a Routing header of the specified
                    130: .Fa type .
                    131: The
                    132: .Li cmsg_len
                    133: member of the
                    134: .Li cmsghdr
                    135: structure is initialized to the
                    136: size of the structure plus the amount of space required by the
                    137: Routing header.
                    138: The
                    139: .Li cmsg_level
                    140: and
                    141: .Li cmsg_type
                    142: members are also initialized as required.
                    143: .Pp
                    144: The caller must allocate the buffer and its size can be determined by
                    145: calling
                    146: .Fn inet6_rthdr_space .
                    147: .Pp
                    148: Upon success the return value is the pointer to the
                    149: .Li cmsghdr
                    150: structure, and this is then used as the first argument to the next
                    151: two functions.
                    152: Upon an error the return value is
                    153: .Dv NULL .
                    154: .\"
                    155: .Ss inet6_rthdr_add
                    156: This function adds the address pointed to by
                    157: .Fa addr
                    158: to the end of the
                    159: Routing header being constructed and sets the type of this hop to the
                    160: value of
                    161: .Fa flags .
                    162: For an IPv6 Type 0 Routing header,
                    163: .Fa flags
                    164: must be
                    165: either
                    166: .Dv IPV6_RTHDR_LOOSE
                    167: or
                    168: .Dv IPV6_RTHDR_STRICT .
                    169: .Pp
                    170: If successful, the
                    171: .Li cmsg_len
                    172: member of the
                    173: .Li cmsghdr
                    174: structure is
                    175: updated to account for the new address in the Routing header and the
                    176: return value of the function is 0.
                    177: Upon an error the return value of
                    178: the function is -1.
                    179: .\"
                    180: .Ss inet6_rthdr_lasthop
                    181: This function specifies the Strict/Loose flag for the final hop of a
                    182: Routing header.
                    183: For an IPv6 Type 0 Routing header,
                    184: .Fa flags
                    185: must be either
                    186: .Dv IPV6_RTHDR_LOOSE
                    187: or
                    188: .Dv IPV6_RTHDR_STRICT .
                    189: .Pp
                    190: The return value of the function is 0 upon success, or -1 upon an error.
                    191: .Pp
                    192: Notice that a Routing header specifying
                    193: .Li N
                    194: intermediate nodes requires
                    195: .Li N+1
                    196: Strict/Loose flags.
                    197: This requires
                    198: .Li N
                    199: calls to
                    200: .Fn inet6_rthdr_add
                    201: followed by one call to
                    202: .Fn inet6_rthdr_lasthop .
                    203: .\"
                    204: .Ss inet6_rthdr_reverse
                    205: This function takes a Routing header that was received as ancillary
                    206: data
                    207: .Po
                    208: pointed to by the first argument,
                    209: .Fa in
                    210: .Pc
                    211: and writes a new Routing
                    212: header that sends datagrams along the reverse of that route.
                    213: Both
                    214: arguments are allowed to point to the same buffer
                    215: .Pq that is, the reversal can occur in place .
                    216: .Pp
                    217: The return value of the function is 0 on success, or -1 upon an
                    218: error.
                    219: .\"
                    220: .Ss inet6_rthdr_segments
                    221: This function returns the number of segments
                    222: .Pq addresses
                    223: contained in
                    224: the Routing header described by
                    225: .Fa cmsg .
                    226: On success the return value is
                    227: between 1 and 23, inclusive.
                    228: The return value of the function is -1 upon an error.
                    229: .\"
                    230: .Ss inet6_rthdr_getaddr
                    231: This function returns a pointer to the IPv6 address specified by
                    232: .Fa index
                    233: .Po
                    234: which must have a value between 1 and the value returned by
                    235: .Fn inet6_rthdr_segments
                    236: .Pc
                    237: in the Routing header described by
                    238: .Fa cmsg .
                    239: An
                    240: application should first call
                    241: .Fn inet6_rthdr_segments
                    242: to obtain the number of segments in the Routing header.
                    243: .Pp
                    244: Upon an error the return value of the function is
                    245: .Dv NULL .
                    246: .\"
                    247: .Ss inet6_rthdr_getflags
                    248: This function returns the flags value specified by
                    249: .Fa index
                    250: .Po
                    251: which must
                    252: have a value between 0 and the value returned by
                    253: .Fn inet6_rthdr_segments
                    254: .Pc
                    255: in the Routing header described by
                    256: .Fa cmsg .
                    257: For an IPv6 Type 0 Routing header the return value will be either
                    258: .Dv IPV6_RTHDR_LOOSE
                    259: or
                    260: .Dv IPV6_RTHDR_STRICT .
                    261: .Pp
                    262: Upon an error the return value of the function is -1.
                    263: .Pp
                    264: Note: Addresses are indexed starting at 1, and flags starting at 0,
                    265: to maintain consistency with the terminology and figures in RFC 2460.
                    266: .\"
                    267: .Sh EXAMPLES
                    268: RFC 2292 gives comprehensive examples in chapter 8.
                    269: .\"
                    270: .Sh DIAGNOSTICS
                    271: .Fn inet6_rthdr_space
                    272: returns 0 on errors.
                    273: .Pp
                    274: .Fn inet6_rthdr_add ,
                    275: .Fn inet6_rthdr_lasthop
                    276: and
                    277: .Fn inet6_rthdr_reverse
                    278: return 0 on success, and returns -1 on error.
                    279: .Pp
                    280: .Fn inet6_rthdr_init
                    281: and
                    282: .Fn inet6_rthdr_getaddr
                    283: return
                    284: .Dv NULL
                    285: on error.
                    286: .Pp
                    287: .Fn inet6_rthdr_segments
                    288: and
                    289: .Fn inet6_rthdr_getflags
                    290: return -1 on error.
                    291: .\"
                    292: .Sh SEE ALSO
                    293: .Rs
                    294: .%A W. Stevens
                    295: .%A M. Thomas
                    296: .%T "Advanced Sockets API for IPv6"
                    297: .%N RFC 2292
                    298: .%D February 1998
                    299: .Re
                    300: .Rs
                    301: .%A S. Deering
                    302: .%A R. Hinden
                    303: .%T "Internet Protocol, Version 6 (IPv6) Specification"
                    304: .%N RFC 2460
                    305: .%D December 1998
                    306: .Re
                    307: .\"
                    308: .Sh STANDARDS
                    309: The functions
                    310: are documented in
                    311: .Dq Advanced Sockets API for IPv6
                    312: .Pq RFC 2292 .
                    313: .\"
                    314: .Sh HISTORY
                    315: The implementation first appeared in KAME advanced networking kit.
                    316: .\"
                    317: .Sh BUGS
                    318: The text was shamelessly copied from RFC 2292.
                    319: .Pp
                    320: .Fn inet6_rthdr_reverse
                    321: is not implemented yet.

CVSweb <webmaster@jp.NetBSD.org>