gen.subproj/inet6_rth_space.3

   1 .\"     $KAME: inet6_rth_space.3,v 1.7 2005/01/05 03:00:44 itojun Exp $
   2 .\"
   3 .\" Copyright (C) 2004 WIDE Project.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the project nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD: src/lib/libc/net/inet6_rth_space.3,v 1.10.10.1.4.1 2010/06/14 02:09:06 kensmith Exp $
  31 .\"
  32 .Dd December 24, 2004
  33 .Dt INET6_RTH_SPACE 3
  34 .Os
  35 .\"
  36 .Sh NAME
  37 .Nm inet6_rth_space ,
  38 .Nm inet6_rth_init ,
  39 .Nm inet6_rth_add ,
  40 .Nm inet6_rth_reverse ,
  41 .Nm inet6_rth_segments ,
  42 .Nm inet6_rth_getaddr
  43 .Nd IPv6 Routing Header Options manipulation
  44 .\"
  45 .Sh SYNOPSIS
  46 .Fd #include <netinet6/in6.h>
  47 .Ft socklen_t
  48 .Fn inet6_rth_space "int" "int"
  49 .Ft "void *"
  50 .Fn inet6_rth_init "void *" "socklen_t" "int" "int"
  51 .Ft int
  52 .Fn inet6_rth_add "void *" "const struct in6_addr *"
  53 .Ft int
  54 .Fn inet6_rth_reverse "const void *" "void *"
  55 .Ft int
  56 .Fn inet6_rth_segments "const void *"
  57 .Ft "struct in6_addr *"
  58 .Fn inet6_rth_getaddr "const void *" "int"
  59 .\"
  60 .Sh DESCRIPTION
  61 The IPv6 Advanced API, RFC 3542, defines the functions that an
  62 application calls to build and examine IPv6 Routing headers.
  63 Routing headers are used to perform source routing in IPv6 networks.
  64 The RFC uses the word
  65 .Dq segments
  66 to describe addresses and that is the term used here as well.
  67 All of the functions are defined in the
  68 .In netinet/in.h
  69 header file.
  70 The functions described in this manual page all operate
  71 on routing header structures which are defined in
  72 .In netinet/ip6.h
  73 but which should not need to be modified outside the use of this API.
  74 The size and shape of the route header structures may change, so using
  75 the APIs is a more portable, long term, solution.
  76 .Pp
  77 The functions in the API are split into two groups, those that build a
  78 routing header and those that parse a received routing header.
  79 We will describe the builder functions followed by the parser functions.
  80 .Ss inet6_rth_space
  81 The
  82 .Fn inet6_rth_space
  83 function returns the number of bytes required to hold a Routing Header
  84 of the type, specified in the
  85 .Fa type
  86 argument and containing the number of addresses specified in the
  87 .Fa segments
  88 argument.
  89 When the type is
  90 .Dv IPV6_RTHDR_TYPE_0
  91 the number of segments must be from 0 through 127.
  92 Routing headers of type
  93 .Dv IPV6_RTHDR_TYPE_2
  94 contain only one segment, and are only used with Mobile IPv6.
  95 The return value from this function is the number of bytes required to
  96 store the routing header.
  97 If the value 0 is returned then either the
  98 route header type was not recognized or another error occurred.
  99 .Ss inet6_rth_init
 100 The
 101 .Fn inet6_rth_init
 102 function initializes the pre-allocated buffer pointed to by
 103 .Fa bp
 104 to contain a routing header of the specified type The
 105 .Fa bp_len
 106 argument is used to verify that the buffer is large enough.
 107 The caller must allocate the buffer pointed to by bp.
 108 The necessary buffer size should be determined by calling
 109 .Fn inet6_rth_space
 110 described in the previous sections.
 111 .Pp
 112 The
 113 .Fn inet6_rth_init
 114 function returns a pointer to
 115 .Fa bp
 116 on success and
 117 .Dv NULL
 118 when there is an error.
 119 .Ss inet6_rth_add
 120 The
 121 .Fn inet6_rth_add
 122 function adds the IPv6 address pointed to by
 123 .Fa addr
 124 to the end of the routing header being constructed.
 125 .Pp
 126 A successful addition results in the function returning 0, otherwise
 127 \-1 is returned.
 128 .Ss inet6_rth_reverse
 129 The
 130 .Fn inet6_rth_reverse
 131 function takes a routing header, pointed to by the
 132 argument
 133 .Fa in ,
 134 and writes a new routing header into the argument pointed to by
 135 .Fa out .
 136 The routing header at that sends datagrams along the reverse of that
 137 route.
 138 Both arguments are allowed to point to the same buffer meaning
 139 that the reversal can occur in place.
 140 .Pp
 141 The return value of the function is 0 on success, or \-1 when
 142 there is an error.
 143 .\"
 144 .Pp
 145 The next set of functions operate on a routing header that the
 146 application wants to parse.
 147 In the usual case such a routing header
 148 is received from the network, although these functions can also be
 149 used with routing headers that the application itself created.
 150 .Ss inet6_rth_segments
 151 The
 152 .Fn inet6_rth_segments
 153 function returns the number of segments contained in the
 154 routing header pointed to by
 155 .Fa bp .
 156 The return value is the number of segments contained in the routing
 157 header, or \-1 if an error occurred.
 158 It is not an error for 0 to be
 159 returned as a routing header may contain 0 segments.
 160 .\"
 161 .Ss inet6_rth_getaddr
 162 The
 163 .Fn inet6_rth_getaddr
 164 function is used to retrieve a single address from a routing header.
 165 The
 166 .Fa index
 167 is the location in the routing header from which the application wants
 168 to retrieve an address.
 169 The
 170 .Fa index
 171 parameter must have a value between 0 and one less than the number of
 172 segments present in the routing header.
 173 The
 174 .Fn inet6_rth_segments
 175 function, described in the last section, should be used to determine
 176 the total number of segments in the routing header.
 177 The
 178 .Fn inet6_rth_getaddr
 179 function returns a pointer to an IPv6 address on success or
 180 .Dv NULL
 181 when an error has occurred.
 182 .\"
 183 .Sh EXAMPLES
 184 RFC 3542 gives extensive examples in Section 21, Appendix B.
 185 .Pp
 186 KAME also provides examples in the advapitest directory of its kit.
 187 .\"
 188 .Sh DIAGNOSTICS
 189 The
 190 .Fn inet6_rth_space
 191 and
 192 .Fn inet6_rth_getaddr
 193 functions return 0 on errors.
 194 .Pp
 195 The
 196 .Fn inet6_rthdr_init
 197 function returns
 198 .Dv NULL
 199 on error.
 200 The
 201 .Fn inet6_rth_add
 202 and
 203 .Fn inet6_rth_reverse
 204 functions return 0 on success, or \-1 upon an error.
 205 .\"
 206 .Sh SEE ALSO
 207 .Rs
 208 .%A W. Stevens
 209 .%A M. Thomas
 210 .%A E. Nordmark
 211 .%A T. Jinmei
 212 .%T "Advanced Sockets API for IPv6"
 213 .%N RFC 3542
 214 .%D May 2003
 215 .Re
 216 .Rs
 217 .%A S. Deering
 218 .%A R. Hinden
 219 .%T "Internet Protocol, Version 6 (IPv6) Specification"
 220 .%N RFC2460
 221 .%D December 1998
 222 .Re
 223 .Sh HISTORY
 224 The implementation first appeared in KAME advanced networking kit.