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