lib/libc/net/inet6_rth_space.3

   1 .\"     $NetBSD$
   2 .\"     $KAME: inet6_rth_space.3,v 1.7 2005/01/05 03:00:44 itojun Exp $
   3 .\"
   4 .\" Copyright (C) 2004 WIDE Project.
   5 .\" 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 project 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 PROJECT 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 PROJECT 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 24, 2004
  32 .Dt INET6_RTH_SPACE 3
  33 .Os
  34 .\"
  35 .Sh NAME
  36 .Nm inet6_rth_space ,
  37 .Nm inet6_rth_init ,
  38 .Nm inet6_rth_add ,
  39 .Nm inet6_rth_reverse ,
  40 .Nm inet6_rth_segments ,
  41 .Nm inet6_rth_getaddr
  42 .Nd IPv6 Routing Header Options manipulation
  43 .\"
  44 .Sh SYNOPSIS
  45 .In netinet/in.h
  46 .Ft socklen_t
  47 .Fn inet6_rth_space "int" "int"
  48 .Ft "void *"
  49 .Fn inet6_rth_init "void *" "socklen_t" "int" "int"
  50 .Ft int
  51 .Fn inet6_rth_add "void *" "const struct in6_addr *"
  52 .Ft int
  53 .Fn inet6_rth_reverse "const void *" "void *"
  54 .Ft int
  55 .Fn inet6_rth_segments "const void *"
  56 .Ft "struct in6_addr *"
  57 .Fn inet6_rth_getaddr "const void *" "int"
  58 .\"
  59 .Sh DESCRIPTION
  60 The IPv6 Advanced API, RFC 3542, defines the functions that an
  61 application calls to build and examine IPv6 Routing headers.
  62 Routing headers are used to perform source routing in IPv6 networks.
  63 The RFC uses the word
  64 .Dq segments
  65 to describe addresses and that is the term used here as well.
  66 All of the functions are defined in the
  67 .In netinet/in.h
  68 header file.
  69 The functions described in this manual page all operate
  70 on routing header structures which are defined in
  71 .In netinet/ip6.h
  72 but which should not need to be modified outside the use of this API.
  73 The size and shape of the route header structures may change, so using
  74 the APIs is a more portable, long term, solution.
  75 .Pp
  76 The functions in the API are split into two groups, those that build a
  77 routing header and those that parse a received routing header.
  78 We will describe the builder functions followed by the parser functions.
  79 .Ss inet6_rth_space
  80 The
  81 .Fn inet6_rth_space
  82 function returns the number of bytes required to hold a Routing Header
  83 of the type, specified in the
  84 .Fa type
  85 argument and containing the number of addresses specified in the
  86 .Fa segments
  87 argumment.
  88 When the type is
  89 .Dv IPV6_RTHDR_TYPE_0
  90 the number of segments must be from 0 through 127.
  91 Routing headers of type
  92 .Dv IPV6_RTHDR_TYPE_2
  93 contain only one segment, and are only used with Mobile IPv6.
  94 The return value from this function is the number of bytes required to
  95 store the routing header.
  96 If the value 0 is returned then either the
  97 route header type was not recognized or another error occurred.
  98 .Ss inet6_rth_init
  99 The
 100 .Fn inet6_rth_init
 101 function initializes the pre-allocated buffer pointed to by
 102 .Fa bp
 103 to contain a routing header of the specified type The
 104 .Fa bp_len
 105 argument is used to verify that the buffer is large enough.
 106 The caller must allocate the buffer pointed to by bp.
 107 The necessary buffer size should be determined by calling
 108 .Fn inet6_rth_space
 109 described in the previous sections.
 110 .Pp
 111 The
 112 .Fn inet6_rth_init
 113 function returns a pointer to
 114 .Fa bp
 115 on success and
 116 .Dv NULL
 117 when there is an error.
 118 .Ss inet6_rth_add
 119 The
 120 .Fn inet6_rth_add
 121 function adds the IPv6 address pointed to by
 122 .Fa addr
 123 to the end of the routing header being constructed.
 124 .Pp
 125 A successful addition results in the function returning 0, otherwise
 126 \-1 is returned.
 127 .Ss inet6_rth_reverse
 128 The
 129 .Fn inet6_rth_reverse
 130 function takes a routing header, pointed to by the
 131 argument
 132 .Fa in ,
 133 and writes a new routing header into the argument pointed to by
 134 .Fa out .
 135 The routing header at that sends datagrams along the reverse of that
 136 route.
 137 Both arguments are allowed to point to the same buffer meaning
 138 that the reversal can occur in place.
 139 .Pp
 140 The return value of the function is 0 on success, or \-1 when
 141 there is an error.
 142 .\"
 143 .Pp
 144 The next set of functions operate on a routing header that the
 145 application wants to parse.
 146 In the usual case such a routing header
 147 is received from the network, although these functions can also be
 148 used with routing headers that the application itself created.
 149 .Ss inet6_rth_segments
 150 The
 151 .Fn inet6_rth_segments
 152 function returns the number of segments contained in the
 153 routing header pointed to by
 154 .Fa bp .
 155 The return value is the number of segments contained in the routing
 156 header, or \-1 if an error occurred.
 157 It is not an error for 0 to be
 158 returned as a routing header may contain 0 segments.
 159 .\"
 160 .Ss inet6_rth_getaddr
 161 The
 162 .Fn inet6_rth_getaddr
 163 function is used to retrieve a single address from a routing header.
 164 The
 165 .Fa index
 166 is the location in the routing header from which the application wants
 167 to retrieve an address.
 168 The
 169 .Fa index
 170 parameter must have a value between 0 and one less than the number of
 171 segments present in the routing header.
 172 The
 173 .Fn inet6_rth_segments
 174 function, described in the last section, should be used to determine
 175 the total number of segments in the routing header.
 176 The
 177 .Fn inet6_rth_getaddr
 178 function returns a pointer to an IPv6 address on success or
 179 .Dv NULL
 180 when an error has occurred.
 181 .\"
 182 .Sh DIAGNOSTICS
 183 The
 184 .Fn inet6_rth_space
 185 and
 186 .Fn inet6_rth_getaddr
 187 functions return 0 on errors.
 188 .Pp
 189 The
 190 .Fn inet6_rthdr_init
 191 function returns
 192 .Dv NULL
 193 on error.
 194 The
 195 .Fn inet6_rth_add
 196 and
 197 .Fn inet6_rth_reverse
 198 functions return 0 on success, or \-1 upon an error.
 199 .\"
 200 .Sh EXAMPLES
 201 RFC 3542 gives extensive examples in Section 21, Appendix B.
 202 .Pp
 203 KAME also provides examples in the advapitest directory of its kit.
 204 .\"
 205 .Sh SEE ALSO
 206 .Rs
 207 .%A W. Stevens
 208 .%A M. Thomas
 209 .%A E. Nordmark
 210 .%A T. Jinmei
 211 .%T "Advanced Sockets API for IPv6"
 212 .%N RFC 3542
 213 .%D May 2003
 214 .Re
 215 .Rs
 216 .%A S. Deering
 217 .%A R. Hinden
 218 .%T "Internet Protocol, Version 6 (IPv6) Specification"
 219 .%N RFC2460
 220 .%D December 1998
 221 .Re
 222 .Sh HISTORY
 223 The implementation first appeared in KAME advanced networking kit.