net/inet6_rthdr_space.3

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