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