lib/libc/net/inet6_option_space.3

   1 .\"     $NetBSD: inet6_option_space.3,v 1.15 2004/12/20 18:30:26 christos Exp $
   2 .\"     $KAME: inet6_option_space.3,v 1.7 2000/05/17 14:32:13 itojun Exp $
   3 .\"
   4 .\" Copyright (c) 1983, 1987, 1991, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .Dd December 10, 1999
  32 .Dt INET6_OPTION_SPACE 3
  33 .Os
  34 .\"
  35 .Sh NAME
  36 .Nm inet6_option_space ,
  37 .Nm inet6_option_init ,
  38 .Nm inet6_option_append ,
  39 .Nm inet6_option_alloc ,
  40 .Nm inet6_option_next ,
  41 .Nm inet6_option_find
  42 .Nd IPv6 Hop-by-Hop and Destination Options manipulation
  43 .\"
  44 .Sh SYNOPSIS
  45 .In netinet/in.h
  46 .Ft "int"
  47 .Fn inet6_option_space "int nbytes"
  48 .Ft "int"
  49 .Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
  50 .Ft "int"
  51 .Fn inet6_option_append "struct cmsghdr *cmsg" "const uint8_t *typep" "int multx" "int plusy"
  52 .Ft "uint8_t *"
  53 .Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy"
  54 .Ft "int"
  55 .Fn inet6_option_next "const struct cmsghdr *cmsg" "uint8_t **tptrp"
  56 .Ft "int"
  57 .Fn inet6_option_find "const struct cmsghdr *cmsg" "uint8_t **tptrp" "int type"
  58 .\"
  59 .Sh DESCRIPTION
  60 .\"
  61 Building and parsing the Hop-by-Hop and Destination options is
  62 complicated due to alignment constraints, padding and
  63 ancillary data manipulation.
  64 RFC 2292 defines a set of functions to help the application.
  65 The function prototypes for
  66 these functions are all in the
  67 .Aq Pa netinet/in.h
  68 header.
  69 .\"
  70 .Ss inet6_option_space
  71 .Fn inet6_option_space
  72 returns the number of bytes required to hold an option when it is stored as
  73 ancillary data, including the
  74 .Li cmsghdr
  75 structure at the beginning,
  76 and any padding at the end
  77 .Po
  78 to make its size a multiple of 8 bytes
  79 .Pc .
  80 The argument is the size of the structure defining the option,
  81 which must include any pad bytes at the beginning
  82 .Po
  83 the value
  84 .Li y
  85 in the alignment term
  86 .Dq Li xn + y
  87 .Pc ,
  88 the type byte, the length byte, and the option data.
  89 .Pp
  90 Note: If multiple options are stored in a single ancillary data
  91 object, which is the recommended technique, this function
  92 overestimates the amount of space required by the size of
  93 .Li N-1
  94 .Li cmsghdr
  95 structures,
  96 where
  97 .Li N
  98 is the number of options to be stored in the object.
  99 This is of little consequence, since it is assumed that most
 100 Hop-by-Hop option headers and Destination option headers carry only
 101 one option
 102 .Pq appendix B of [RFC 2460] .
 103 .\"
 104 .Ss inet6_option_init
 105 .Fn inet6_option_init
 106 is called once per ancillary data object that will
 107 contain either Hop-by-Hop or Destination options.
 108 It returns
 109 .Li 0
 110 on success or
 111 .Li -1
 112 on an error.
 113 .Pp
 114 .Fa bp
 115 is a pointer to previously allocated space that will contain the
 116 ancillary data object.
 117 It must be large enough to contain all the
 118 individual options to be added by later calls to
 119 .Fn inet6_option_append
 120 and
 121 .Fn inet6_option_alloc .
 122 .Pp
 123 .Fa cmsgp
 124 is a pointer to a pointer to a
 125 .Li cmsghdr
 126 structure.
 127 .Fa *cmsgp
 128 is initialized by this function to point to the
 129 .Li cmsghdr
 130 structure constructed by this function in the buffer pointed to by
 131 .Fa bp .
 132 .Pp
 133 .Fa type
 134 is either
 135 .Dv IPV6_HOPOPTS
 136 or
 137 .Dv IPV6_DSTOPTS .
 138 This
 139 .Fa type
 140 is stored in the
 141 .Li cmsg_type
 142 member of the
 143 .Li cmsghdr
 144 structure pointed to by
 145 .Fa *cmsgp .
 146 .\"
 147 .Ss inet6_option_append
 148 This function appends a Hop-by-Hop option or a Destination option
 149 into an ancillary data object that has been initialized by
 150 .Fn inet6_option_init .
 151 This function returns
 152 .Li 0
 153 if it succeeds or
 154 .Li -1
 155 on an error.
 156 .Pp
 157 .Fa cmsg
 158 is a pointer to the
 159 .Li cmsghdr
 160 structure that must have been
 161 initialized by
 162 .Fn inet6_option_init .
 163 .Pp
 164 .Fa typep
 165 is a pointer to the 8-bit option type.
 166 It is assumed that this
 167 field is immediately followed by the 8-bit option data length field,
 168 which is then followed immediately by the option data.
 169 The caller
 170 initializes these three fields
 171 .Pq the type-length-value, or TLV
 172 before calling this function.
 173 .Pp
 174 The option type must have a value from
 175 .Li 2
 176 to
 177 .Li 255 ,
 178 inclusive.
 179 .Po
 180 .Li 0
 181 and
 182 .Li 1
 183 are reserved for the
 184 .Li Pad1
 185 and
 186 .Li PadN
 187 options, respectively.
 188 .Pc
 189 .Pp
 190 The option data length must have a value between
 191 .Li 0
 192 and
 193 .Li 255 ,
 194 inclusive, and is the length of the option data that follows.
 195 .Pp
 196 .Fa multx
 197 is the value
 198 .Li x
 199 in the alignment term
 200 .Dq Li xn + y .
 201 It must have a value of
 202 .Li 1 ,
 203 .Li 2 ,
 204 .Li 4 ,
 205 or
 206 .Li 8 .
 207 .Pp
 208 .Fa plusy
 209 is the value
 210 .Li y
 211 in the alignment term
 212 .Dq Li xn + y .
 213 It must have a value between
 214 .Li 0
 215 and
 216 .Li 7 ,
 217 inclusive.
 218 .\"
 219 .Ss inet6_option_alloc
 220 This function appends a Hop-by-Hop option or a Destination option
 221 into an ancillary data object that has been initialized by
 222 .Fn inet6_option_init .
 223 This function returns a pointer to the 8-bit
 224 option type field that starts the option on success, or
 225 .Dv NULL
 226 on an error.
 227 .Pp
 228 The difference between this function and
 229 .Fn inet6_option_append
 230 is that the latter copies the contents of a previously built option into
 231 the ancillary data object while the current function returns a
 232 pointer to the space in the data object where the option's TLV must
 233 then be built by the caller.
 234 .Pp
 235 .Fa cmsg
 236 is a pointer to the
 237 .Li cmsghdr
 238 structure that must have been
 239 initialized by
 240 .Fn inet6_option_init .
 241 .Pp
 242 .Fa datalen
 243 is the value of the option data length byte for this option.
 244 This value is required as an argument to allow the function to
 245 determine if padding must be appended at the end of the option.
 246 .Po
 247 The
 248 .Fn inet6_option_append
 249 function does not need a data length argument
 250 since the option data length must already be stored by the caller.
 251 .Pc
 252 .Pp
 253 .Fa multx
 254 is the value
 255 .Li x
 256 in the alignment term
 257 .Dq Li xn + y .
 258 It must have a value of
 259 .Li 1 ,
 260 .Li 2 ,
 261 .Li 4 ,
 262 or
 263 .Li 8 .
 264 .Pp
 265 .Fa plusy
 266 is the value
 267 .Li y
 268 in the alignment term
 269 .Dq Li xn + y .
 270 It must have a value between
 271 .Li 0
 272 and
 273 .Li 7 ,
 274 inclusive.
 275 .\"
 276 .Ss inet6_option_next
 277 This function processes the next Hop-by-Hop option or Destination
 278 option in an ancillary data object.
 279 If another option remains to be
 280 processed, the return value of the function is
 281 .Li 0
 282 and
 283 .Fa *tptrp
 284 points to
 285 the 8-bit option type field
 286 .Po
 287 which is followed by the 8-bit option
 288 data length, followed by the option data
 289 .Pc .
 290 If no more options remain
 291 to be processed, the return value is
 292 .Li -1
 293 and
 294 .Fa *tptrp
 295 is
 296 .Dv NULL .
 297 If an error occurs, the return value is
 298 .Li -1
 299 and
 300 .Fa *tptrp
 301 is not
 302 .Dv NULL .
 303 .Pp
 304 .Fa cmsg
 305 is a pointer to
 306 .Li cmsghdr
 307 structure of which
 308 .Li cmsg_level
 309 equals
 310 .Dv IPPROTO_IPV6
 311 and
 312 .Li cmsg_type
 313 equals either
 314 .Dv IPV6_HOPOPTS
 315 or
 316 .Dv IPV6_DSTOPTS .
 317 .Pp
 318 .Fa tptrp
 319 is a pointer to a pointer to an 8-bit byte and
 320 .Fa *tptrp
 321 is used
 322 by the function to remember its place in the ancillary data object
 323 each time the function is called.
 324 The first time this function is
 325 called for a given ancillary data object,
 326 .Fa *tptrp
 327 must be set to
 328 .Dv NULL .
 329 .Pp
 330 Each time this function returns success,
 331 .Fa *tptrp
 332 points to the 8-bit
 333 option type field for the next option to be processed.
 334 .\"
 335 .Ss inet6_option_find
 336 This function is similar to the previously described
 337 .Fn inet6_option_next
 338 function, except this function lets the caller
 339 specify the option type to be searched for, instead of always
 340 returning the next option in the ancillary data object.
 341 .Fa cmsg
 342 is a
 343 pointer to
 344 .Li cmsghdr
 345 structure of which
 346 .Li cmsg_level
 347 equals
 348 .Dv IPPROTO_IPV6
 349 and
 350 .Li cmsg_type
 351 equals either
 352 .Dv IPV6_HOPOPTS
 353 or
 354 .Dv IPV6_DSTOPTS .
 355 .Pp
 356 .Fa tptrp
 357 is a pointer to a pointer to an 8-bit byte and
 358 .Fa *tptrp
 359 is used
 360 by the function to remember its place in the ancillary data object
 361 each time the function is called.
 362 The first time this function is
 363 called for a given ancillary data object,
 364 .Fa *tptrp
 365 must be set to
 366 .Dv NULL .
 367 .Pa
 368 This function starts searching for an option of the specified type
 369 beginning after the value of
 370 .Fa *tptrp .
 371 If an option of the specified
 372 type is located, this function returns
 373 .Li 0
 374 and
 375 .Fa *tptrp
 376 points to the 8-
 377 bit option type field for the option of the specified type.
 378 If an
 379 option of the specified type is not located, the return value is
 380 .Li -1
 381 and
 382 .Fa *tptrp
 383 is
 384 .Dv NULL .
 385 If an error occurs, the return value is
 386 .Li -1
 387 and
 388 .Fa *tptrp
 389 is not
 390 .Dv NULL .
 391 .\"
 392 .Sh EXAMPLES
 393 RFC 2292 gives comprehensive examples in chapter 6.
 394 .\"
 395 .Sh DIAGNOSTICS
 396 .Fn inet6_option_init
 397 and
 398 .Fn inet6_option_append
 399 return
 400 .Li 0
 401 on success or
 402 .Li -1
 403 on an error.
 404 .Pp
 405 .Fn inet6_option_alloc
 406 returns
 407 .Dv NULL
 408 on an error.
 409 .Pp
 410 On errors,
 411 .Fn inet6_option_next
 412 and
 413 .Fn inet6_option_find
 414 return
 415 .Li -1
 416 setting
 417 .Fa *tptrp
 418 to non
 419 .Dv NULL
 420 value.
 421 .\"
 422 .Sh SEE ALSO
 423 .Rs
 424 .%A W. Stevens
 425 .%A M. Thomas
 426 .%T "Advanced Sockets API for IPv6"
 427 .%N RFC 2292
 428 .%D February 1998
 429 .Re
 430 .Rs
 431 .%A S. Deering
 432 .%A R. Hinden
 433 .%T "Internet Protocol, Version 6 (IPv6) Specification"
 434 .%N RFC 2460
 435 .%D December 1998
 436 .Re
 437 .\"
 438 .Sh STANDARDS
 439 The functions
 440 are documented in
 441 .Dq Advanced Sockets API for IPv6
 442 .Pq RFC 2292 .
 443 .\"
 444 .Sh HISTORY
 445 The implementation first appeared in KAME advanced networking kit.
 446 .\"
 447 .Sh BUGS
 448 The text was shamelessly copied from RFC 2292.