lib/libc/net/inet6_rthdr_space.3

   1 .\"     $KAME: inet6_rthdr_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $
   2 .\"     $FreeBSD: src/lib/libc/net/inet6_rthdr_space.3,v 1.14 2005/01/23 16:02:48 gnn Exp $
   3 .\"     $DragonFly: src/lib/libc/net/inet6_rthdr_space.3,v 1.4 2006/02/17 19:35:06 swildner Exp $
   4 .\"
   5 .\" Copyright (C) 2004 WIDE Project.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the project nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd December 27, 2004
  33 .Dt INET6_RTHDR_SPACE 3
  34 .Os
  35 .\"
  36 .Sh NAME
  37 .Nm inet6_rthdr_space ,
  38 .Nm inet6_rthdr_init ,
  39 .Nm inet6_rthdr_add ,
  40 .Nm inet6_rthdr_lasthop ,
  41 .Nm inet6_rthdr_reverse ,
  42 .Nm inet6_rthdr_segments ,
  43 .Nm inet6_rthdr_getaddr ,
  44 .Nm inet6_rthdr_getflags
  45 .Nd IPv6 Routing Header Options Manipulation
  46 .\"
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In sys/types.h
  51 .In netinet/in.h
  52 .Ft size_t
  53 .Fn inet6_rthdr_space "int type" "int segments"
  54 .Ft "struct cmsghdr *"
  55 .Fn inet6_rthdr_init "void *bp" "int type"
  56 .Ft int
  57 .Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags"
  58 .Ft int
  59 .Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags"
  60 .Ft int
  61 .Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out"
  62 .Ft int
  63 .Fn inet6_rthdr_segments "const struct cmsghdr *cmsg"
  64 .Ft "struct in6_addr *"
  65 .Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index"
  66 .Ft int
  67 .Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index"
  68 .\"
  69 .Sh DESCRIPTION
  70 .\"The RFC 2292 IPv6 Advanced API has been deprecated in favor of the
  71 .\"newer, RFC 3542 APIs.
  72 .\"On platforms that support it, currently only
  73 .\"FreeBSD, please use the newer API to manipulate routing header
  74 .\"options.
  75 .\".Pp
  76 The RFC 2292 IPv6 Advanced API defined eight functions for
  77 applications to use for building and parsing routing headers.
  78 The
  79 eight functions are split into two groups, the first of which builds
  80 the header and the second of which can parse it.
  81 The function prototypes for these functions are all in the
  82 .In netinet/in.h
  83 header.
  84 Although direct manipulation of a routing header is possible
  85 this set of APIs make it unnecessary and such direct manipulation
  86 should be avoided so that changes to the underlying structures do not
  87 break applications.
  88 .Pp
  89 Please note that RFC 2292 uses the term
  90 .Dq segments
  91 instead of the term
  92 .Dq addresses
  93 but they are considered equivalent for this manual page.
  94 .\"
  95 .Ss inet6_rthdr_space
  96 The
  97 .Fn inet6_rthdr_space
  98 function returns the number of bytes required to hold a routing header
  99 of the specified
 100 .Fa type
 101 and containing the specified number of
 102 .Fa segments .
 103 Only one
 104 .Fa type
 105 is supported,
 106 .Dv IPV6_RTHDR_TYPE_0 ,
 107 and it can hold from 1 to 23 segments.
 108 The return value includes the
 109 size of the cmsghdr structure that precedes the routing header, and
 110 any required padding.
 111 .Pp
 112 A return value of 0 indicates an error.
 113 Either the type was specified
 114 incorrectly, or the number of segments was less than one or greater
 115 than 23.
 116 .Pp
 117 Note: The
 118 .Fn inet6_rthdr_space
 119 function only returns the size required by the routing header and does
 120 not allocate memory for the caller.
 121 .\"
 122 .Ss inet6_rthdr_init
 123 The
 124 .Fn inet6_rthdr_init
 125 function initializes a buffer, pointed to by
 126 .Fa bp
 127 with an appropriate
 128 .Li cmsghdr
 129 structure followed by a routing header of the specified
 130 .Fa type .
 131 .Pp
 132 The caller must use the
 133 .Fn inet6_rthdr_space
 134 function to determine the size of the buffer, and then allocate that
 135 buffer before calling
 136 .Fn inet6_rthdr_init .
 137 .Pp
 138 The return value is a pointer to a
 139 .Li cmsghdr
 140 structure, which is used as the first argument to the
 141 .Fn inet6_rthdr_add
 142 and
 143 .Fn inet6_rthdr_lasthop
 144 functions in order to construct the routing header.
 145 When an error occurs the return value is
 146 .Dv NULL .
 147 .\"
 148 .Ss inet6_rthdr_add
 149 The
 150 .Fn inet6_rthdr_add
 151 function adds the IPv6 address pointed to by
 152 .Fa addr
 153 to the end of the
 154 routing header being constructed and sets the type of this address to the
 155 value of
 156 .Fa flags .
 157 The
 158 .Fa flags
 159 must be either
 160 .Dv IPV6_RTHDR_LOOSE
 161 or
 162 .Dv IPV6_RTHDR_STRICT
 163 indicating whether loose or strict source routing is required.
 164 .Pp
 165 When the function succeeds it returns 0, otherwise \-1 is returned.
 166 .\"
 167 .Ss inet6_rthdr_lasthop
 168 The
 169 .Fn inet6_rthdr_lasthop
 170 function specifies the strict or loose flag for the final hop of a
 171 routing header.
 172 The
 173 .Fa flags
 174 must be either
 175 .Dv IPV6_RTHDR_LOOSE
 176 or
 177 .Dv IPV6_RTHDR_STRICT .
 178 .Pp
 179 The return value of the function is 0 upon success, and \-1 when an
 180 error has occurred.
 181 .Pp
 182 Please note that a routing header specifying
 183 .Li N
 184 intermediate nodes requires
 185 .Li N+1
 186 strict or loose flags meaning that
 187 .Fn inet6_rthdr_add
 188 must be called
 189 .Li N
 190 times and then
 191 .Fn inet6_rthdr_lasthop
 192 must be called once.
 193 .\"
 194 .Ss inet6_rthdr_reverse
 195 This function was never implemented.
 196 .Pp
 197 The following four functions provide an API for parsing a received
 198 routing header.
 199 .\"
 200 .Ss inet6_rthdr_segments
 201 The
 202 .Fn inet6_rthdr_segments
 203 function returns the number of segments contained in the Routing
 204 header pointed to by the
 205 .Fa cmsg
 206 argument.
 207 On success the return value is from 1 to 23.
 208 When an error occurs \-1 is returned.
 209 .\"
 210 .Ss inet6_rthdr_getaddr
 211 The
 212 .Fn inet6_rthdr_getaddr
 213 function returns a pointer to the IPv6 address specified by the
 214 .Fa index
 215 argument from the routing header pointed to by
 216 .Fa cmsg .
 217 The index must be between 1 and the number returned by
 218 .Fn inet6_rthdr_segments
 219 described above.
 220 An application must call
 221 .Fn inet6_rthdr_segments
 222 to obtain the number of segments in the routing header.
 223 .Pp
 224 If an error occurs the
 225 .Dv NULL
 226 is returned.
 227 .\"
 228 .Ss inet6_rthdr_getflags
 229 The
 230 .Fn inet6_rthdr_getflags
 231 function returns the flags value of the segment specified by
 232 .Fa index
 233 of the routing header pointed to by
 234 .Fa cmsg .
 235 The
 236 .Fa index
 237 argument must be between 0 and the value returned by
 238 .Fn inet6_rthdr_segments .
 239 The return value will be either
 240 .Dv IPV6_RTHDR_LOOSE
 241 or
 242 .Dv IPV6_RTHDR_STRICT
 243 indicating whether loose or strict source routing was requested for
 244 that segment.
 245 .Pp
 246 When an error occurs \-1 is returned.
 247 .Pp
 248 Note: Flags begin at index 0 while segments begin at index 1, to
 249 maintain consistency with the terminology and figures in RFC2460.
 250 .\"
 251 .Sh EXAMPLES
 252 RFC2292 gives comprehensive examples in chapter 8.
 253 .\"
 254 .Sh DIAGNOSTICS
 255 The
 256 .Fn inet6_rthdr_space
 257 function returns 0 when an error occurs.
 258 .Pp
 259 The
 260 .Fn inet6_rthdr_add ,
 261 .Fn inet6_rthdr_lasthop
 262 functions return 0 on success, and \-1 on error.
 263 .Pp
 264 The
 265 .Fn inet6_rthdr_init
 266 and
 267 .Fn inet6_rthdr_getaddr
 268 functions
 269 return
 270 .Dv NULL
 271 on error.
 272 .Pp
 273 The
 274 .Fn inet6_rthdr_segments
 275 and
 276 .Fn inet6_rthdr_getflags
 277 functions return -1 on error.
 278 .\"
 279 .Sh SEE ALSO
 280 .Rs
 281 .%A W. Stevens
 282 .%A M. Thomas
 283 .%T "Advanced Sockets API for IPv6"
 284 .%N RFC2292
 285 .%D February 1998
 286 .Re
 287 .Rs
 288 .%A S. Deering
 289 .%A R. Hinden
 290 .%T "Internet Protocol, Version 6 (IPv6) Specification"
 291 .%N RFC2460
 292 .%D December 1998
 293 .Re
 294 .\"
 295 .Sh HISTORY
 296 The implementation first appeared in KAME advanced networking kit.
 297 .\"
 298 .Sh BUGS
 299 The
 300 .Fn inet6_rthdr_reverse
 301 function was never implemented.
 302 .\".Pp
 303 .\"This API is deprecated in favor of
 304 .\".Xr inet6_rth_space 3
 305 .\".Sh SEE ALSO
 306 .\".Xr inet6_rth_space 3