lib/libc/net/inet6_option_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_option_space.3,v 1.4 2000/02/05 10:32:24 jinmei Exp $
  33 .\" $FreeBSD: src/lib/libc/net/inet6_option_space.3,v 1.1.2.7 2002/12/29 16:35:34 schweikh Exp $
  34 .\" $DragonFly: src/lib/libc/net/inet6_option_space.3,v 1.2 2003/06/17 04:26:44 dillon Exp $
  35 .\"
  36 .Dd December 10, 1999
  37 .Dt INET6_OPTION_SPACE 3
  38 .Os
  39 .\"
  40 .Sh NAME
  41 .Nm inet6_option_space ,
  42 .Nm inet6_option_init ,
  43 .Nm inet6_option_append ,
  44 .Nm inet6_option_alloc ,
  45 .Nm inet6_option_next ,
  46 .Nm inet6_option_find
  47 .Nd IPv6 Hop-by-Hop and Destination Options manipulation
  48 .\"
  49 .Sh LIBRARY
  50 .Lb libc
  51 .Sh SYNOPSIS
  52 .In sys/types.h
  53 .In netinet/in.h
  54 .Ft "int"
  55 .Fn inet6_option_space "int nbytes"
  56 .Ft "int"
  57 .Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
  58 .Ft "int"
  59 .Fn inet6_option_append "struct cmsghdr *cmsg" "const u_int8_t *typep" "int multx" "int plusy"
  60 .Ft "u_int8_t *"
  61 .Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy"
  62 .Ft "int"
  63 .Fn inet6_option_next "const struct cmsghdr *cmsg" "u_int8_t **tptrp"
  64 .Ft "int"
  65 .Fn inet6_option_find "const struct cmsghdr *cmsg" "u_int8_t **tptrp" "int type"
  66 .\"
  67 .Sh DESCRIPTION
  68 .\"
  69 Building and parsing the Hop-by-Hop and Destination options is
  70 complicated due to alignment constraints, padding and
  71 ancillary data manipulation.
  72 RFC2292 defines a set of functions to help the application.
  73 The function prototypes for
  74 these functions are all in the
  75 .Aq Li netinet/in.h
  76 header.
  77 .\"
  78 .Ss inet6_option_space
  79 .Fn inet6_option_space
  80 returns the number of bytes required to hold an option when it is stored as
  81 ancillary data, including the
  82 .Li cmsghdr
  83 structure at the beginning,
  84 and any padding at the end
  85 (to make its size a multiple of 8 bytes).
  86 The argument is the size of the structure defining the option,
  87 which must include any pad bytes at the beginning
  88 (the value
  89 .Li y
  90 in the alignment term
  91 .Dq Li "xn + y" ) ,
  92 the type byte, the length byte, and the option data.
  93 .Pp
  94 Note: If multiple options are stored in a single ancillary data
  95 object, which is the recommended technique, this function
  96 overestimates the amount of space required by the size of
  97 .Li N-1
  98 .Li cmsghdr
  99 structures,
 100 where
 101 .Li N
 102 is the number of options to be stored in the object.
 103 This is of little consequence, since it is assumed that most
 104 Hop-by-Hop option headers and Destination option headers carry only
 105 one option
 106 (appendix B of [RFC-2460]).
 107 .\"
 108 .Ss inet6_option_init
 109 .Fn inet6_option_init
 110 is called once per ancillary data object that will
 111 contain either Hop-by-Hop or Destination options.
 112 It returns
 113 .Li 0
 114 on success or
 115 .Li -1
 116 on an error.
 117 .Pp
 118 .Fa bp
 119 is a pointer to previously allocated space that will contain the
 120 ancillary data object.
 121 It must be large enough to contain all the
 122 individual options to be added by later calls to
 123 .Fn inet6_option_append
 124 and
 125 .Fn inet6_option_alloc .
 126 .Pp
 127 .Fa cmsgp
 128 is a pointer to a pointer to a
 129 .Li cmsghdr
 130 structure.
 131 .Fa *cmsgp
 132 is initialized by this function to point to the
 133 .Li cmsghdr
 134 structure constructed by this function in the buffer pointed to by
 135 .Fa bp .
 136 .Pp
 137 .Fa type
 138 is either
 139 .Dv IPV6_HOPOPTS
 140 or
 141 .Dv IPV6_DSTOPTS .
 142 This
 143 .Fa type
 144 is stored in the
 145 .Li cmsg_type
 146 member of the
 147 .Li cmsghdr
 148 structure pointed to by
 149 .Fa *cmsgp .
 150 .\"
 151 .Ss inet6_option_append
 152 This function appends a Hop-by-Hop option or a Destination option
 153 into an ancillary data object that has been initialized by
 154 .Fn inet6_option_init .
 155 This function returns
 156 .Li 0
 157 if it succeeds or
 158 .Li -1
 159 on an error.
 160 .Pp
 161 .Fa cmsg
 162 is a pointer to the
 163 .Li cmsghdr
 164 structure that must have been
 165 initialized by
 166 .Fn inet6_option_init .
 167 .Pp
 168 .Fa typep
 169 is a pointer to the 8-bit option type.
 170 It is assumed that this
 171 field is immediately followed by the 8-bit option data length field,
 172 which is then followed immediately by the option data.
 173 The caller
 174 initializes these three fields
 175 (the type-length-value, or TLV)
 176 before calling this function.
 177 .Pp
 178 The option type must have a value from
 179 .Li 2
 180 to
 181 .Li 255 ,
 182 inclusive.
 183 .Li ( 0
 184 and
 185 .Li 1
 186 are reserved for the
 187 .Li Pad1
 188 and
 189 .Li PadN
 190 options, respectively.)
 191 .Pp
 192 The option data length must have a value between
 193 .Li 0
 194 and
 195 .Li 255 ,
 196 inclusive, and is the length of the option data that follows.
 197 .Pp
 198 .Fa multx
 199 is the value
 200 .Li x
 201 in the alignment term
 202 .Dq Li xn + y .
 203 It must have a value of
 204 .Li 1 ,
 205 .Li 2 ,
 206 .Li 4 ,
 207 or
 208 .Li 8 .
 209 .Pp
 210 .Fa plusy
 211 is the value
 212 .Li y
 213 in the alignment term
 214 .Dq Li xn + y .
 215 It must have a value between
 216 .Li 0
 217 and
 218 .Li 7 ,
 219 inclusive.
 220 .\"
 221 .Ss inet6_option_alloc
 222 This function appends a Hop-by-Hop option or a Destination option
 223 into an ancillary data object that has been initialized by
 224 .Fn inet6_option_init .
 225 This function returns a pointer to the 8-bit
 226 option type field that starts the option on success, or
 227 .Dv NULL
 228 on an error.
 229 .Pp
 230 The difference between this function and
 231 .Fn inet6_option_append
 232 is that the latter copies the contents of a previously built option into
 233 the ancillary data object while the current function returns a
 234 pointer to the space in the data object where the option's TLV must
 235 then be built by the caller.
 236 .Pp
 237 .Fa cmsg
 238 is a pointer to the
 239 .Li cmsghdr
 240 structure that must have been
 241 initialized by
 242 .Fn inet6_option_init .
 243 .Pp
 244 .Fa datalen
 245 is the value of the option data length byte for this option.
 246 This value is required as an argument to allow the function to
 247 determine if padding must be appended at the end of the option.
 248 (The
 249 .Fn inet6_option_append
 250 function does not need a data length argument
 251 since the option data length must already be stored by the caller.)
 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 (which is followed by the 8-bit option
 287 data length, followed by the option data).
 288 If no more options remain
 289 to be processed, the return value is
 290 .Li -1
 291 and
 292 .Fa *tptrp
 293 is
 294 .Dv NULL .
 295 If an error occurs, the return value is
 296 .Li -1
 297 and
 298 .Fa *tptrp
 299 is not
 300 .Dv NULL .
 301 .Pp
 302 .Fa cmsg
 303 is a pointer to
 304 .Li cmsghdr
 305 structure of which
 306 .Li cmsg_level
 307 equals
 308 .Dv IPPROTO_IPV6
 309 and
 310 .Li cmsg_type
 311 equals either
 312 .Dv IPV6_HOPOPTS
 313 or
 314 .Dv IPV6_DSTOPTS .
 315 .Pp
 316 .Fa tptrp
 317 is a pointer to a pointer to an 8-bit byte and
 318 .Fa *tptrp
 319 is used
 320 by the function to remember its place in the ancillary data object
 321 each time the function is called.
 322 The first time this function is
 323 called for a given ancillary data object,
 324 .Fa *tptrp
 325 must be set to
 326 .Dv NULL .
 327 .Pp
 328 Each time this function returns success,
 329 .Fa *tptrp
 330 points to the 8-bit
 331 option type field for the next option to be processed.
 332 .\"
 333 .Ss inet6_option_find
 334 This function is similar to the previously described
 335 .Fn inet6_option_next
 336 function, except this function lets the caller
 337 specify the option type to be searched for, instead of always
 338 returning the next option in the ancillary data object.
 339 .Fa cmsg
 340 is a
 341 pointer to
 342 .Li cmsghdr
 343 structure of which
 344 .Li cmsg_level
 345 equals
 346 .Dv IPPROTO_IPV6
 347 and
 348 .Li cmsg_type
 349 equals either
 350 .Dv IPV6_HOPOPTS
 351 or
 352 .Dv IPV6_DSTOPTS .
 353 .Pp
 354 .Fa tptrp
 355 is a pointer to a pointer to an 8-bit byte and
 356 .Fa *tptrp
 357 is used
 358 by the function to remember its place in the ancillary data object
 359 each time the function is called.
 360 The first time this function is
 361 called for a given ancillary data object,
 362 .Fa *tptrp
 363 must be set to
 364 .Dv NULL .
 365 .Pa
 366 This function starts searching for an option of the specified type
 367 beginning after the value of
 368 .Fa *tptrp .
 369 If an option of the specified
 370 type is located, this function returns
 371 .Li 0
 372 and
 373 .Fa *tptrp
 374 points to the 8-
 375 bit option type field for the option of the specified type.
 376 If an
 377 option of the specified type is not located, the return value is
 378 .Li -1
 379 and
 380 .Fa *tptrp
 381 is
 382 .Dv NULL .
 383 If an error occurs, the return value is
 384 .Li -1
 385 and
 386 .Fa *tptrp
 387 is not
 388 .Dv NULL .
 389 .\"
 390 .Sh DIAGNOSTICS
 391 .Fn inet6_option_init
 392 and
 393 .Fn inet6_option_append
 394 return
 395 .Li 0
 396 on success or
 397 .Li -1
 398 on an error.
 399 .Pp
 400 .Fn inet6_option_alloc
 401 returns
 402 .Dv NULL
 403 on an error.
 404 .Pp
 405 On errors,
 406 .Fn inet6_option_next
 407 and
 408 .Fn inet6_option_find
 409 return
 410 .Li -1
 411 setting
 412 .Fa *tptrp
 413 to non
 414 .Dv NULL
 415 value.
 416 .\"
 417 .Sh EXAMPLES
 418 RFC2292 gives comprehensive examples in chapter 6.
 419 .\"
 420 .Sh SEE ALSO
 421 .Rs
 422 .%A W. Stevens
 423 .%A M. Thomas
 424 .%T "Advanced Sockets API for IPv6"
 425 .%N RFC2292
 426 .%D February 1998
 427 .Re
 428 .Rs
 429 .%A S. Deering
 430 .%A R. Hinden
 431 .%T "Internet Protocol, Version 6 (IPv6) Specification"
 432 .%N RFC2460
 433 .%D December 1998
 434 .Re
 435 .\"
 436 .Sh HISTORY
 437 The implementation first appeared in KAME advanced networking kit.
 438 .\"
 439 .Sh STANDARDS
 440 The functions
 441 are documented in
 442 .Dq Advanced Sockets API for IPv6
 443 (RFC2292).
 444 .\"
 445 .Sh BUGS
 446 The text was shamelessly copied from RFC2292.