packages/net/common/v2_0/doc/manpages/net/inet6_option_space.3

   1 .\"     $OpenBSD: inet6_option_space.3,v 1.8 2001/06/23 05:57:04 deraadt 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. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .Dd December 10, 1999
  36 .Dt INET6_OPTION_SPACE 3
  37 .Os
  38 .\"
  39 .Sh NAME
  40 .Nm inet6_option_space ,
  41 .Nm inet6_option_init ,
  42 .Nm inet6_option_append ,
  43 .Nm inet6_option_alloc ,
  44 .Nm inet6_option_next ,
  45 .Nm inet6_option_find
  46 .Nd IPv6 Hop-by-Hop and Destination Options manipulation
  47 .\"
  48 .Sh SYNOPSIS
  49 .Fd #include <netinet/in.h>
  50 .Ft "int"
  51 .Fn inet6_option_space "int nbytes"
  52 .Ft "int"
  53 .Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
  54 .Ft "int"
  55 .Fn inet6_option_append "struct cmsghdr *cmsg" "const u_int8_t *typep" "int multx" "int plusy"
  56 .Ft "u_int8_t *"
  57 .Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy";
  58 .Ft "int"
  59 .Fn inet6_option_next "const struct cmsghdr *cmsg" "u_int8_t **tptrp"
  60 .Ft "int"
  61 .Fn inet6_option_find "const struct cmsghdr *cmsg" "u_int8_t **tptrp" "int type"
  62 .\"
  63 .Sh DESCRIPTION
  64 .\"
  65 Building and parsing the Hop-by-Hop and Destination options is
  66 complicated due to alignment constranints, padding and
  67 ancillary data manipulation.
  68 RFC2292 defines a set of functions to help the application.
  69 The function prototypes for
  70 these functions are all in the
  71 .Aq Li netinet/in.h
  72 header.
  73 .\"
  74 .Ss inet6_option_space
  75 .Fn inet6_option_space
  76 returns the number of bytes required to hold an option when it is stored as
  77 ancillary data, including the
  78 .Li cmsghdr
  79 structure at the beginning,
  80 and any padding at the end
  81 .Po
  82 to make its size a multiple of 8 bytes
  83 .Pc .
  84 The argument is the size of the structure defining the option,
  85 which must include any pad bytes at the beginning
  86 .Po
  87 the value
  88 .Li y
  89 in the alignment term
  90 .Dq Li xn + y
  91 .Pc ,
  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 .Pq 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 .Pq 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 .Po
 184 .Li 0
 185 and
 186 .Li 1
 187 are reserved for the
 188 .Li Pad1
 189 and
 190 .Li PadN
 191 options, respectively.
 192 .Pc
 193 .Pp
 194 The option data length must have a value between
 195 .Li 0
 196 and
 197 .Li 255 ,
 198 inclusive, and is the length of the option data that follows.
 199 .Pp
 200 .Fa multx
 201 is the value
 202 .Li x
 203 in the alignment term
 204 .Dq Li xn + y .
 205 It must have a value of
 206 .Li 1 ,
 207 .Li 2 ,
 208 .Li 4 ,
 209 or
 210 .Li 8 .
 211 .Pp
 212 .Fa plusy
 213 is the value
 214 .Li y
 215 in the alignment term
 216 .Dq Li xn + y .
 217 It must have a value between
 218 .Li 0
 219 and
 220 .Li 7 ,
 221 inclusive.
 222 .\"
 223 .Ss inet6_option_alloc
 224 This function appends a Hop-by-Hop option or a Destination option
 225 into an ancillary data object that has been initialized by
 226 .Fn inet6_option_init .
 227 This function returns a pointer to the 8-bit
 228 option type field that starts the option on success, or
 229 .Dv NULL
 230 on an error.
 231 .Pp
 232 The difference between this function and
 233 .Fn inet6_option_append
 234 is that the latter copies the contents of a previously built option into
 235 the ancillary data object while the current function returns a
 236 pointer to the space in the data object where the option's TLV must
 237 then be built by the caller.
 238 .Pp
 239 .Fa cmsg
 240 is a pointer to the
 241 .Li cmsghdr
 242 structure that must have been
 243 initialized by
 244 .Fn inet6_option_init .
 245 .Pp
 246 .Fa datalen
 247 is the value of the option data length byte for this option.
 248 This value is required as an argument to allow the function to
 249 determine if padding must be appended at the end of the option.
 250 .Po
 251 The
 252 .Fn inet6_option_append
 253 function does not need a data length argument
 254 since the option data length must already be stored by the caller.
 255 .Pc
 256 .Pp
 257 .Fa multx
 258 is the value
 259 .Li x
 260 in the alignment term
 261 .Dq Li xn + y .
 262 It must have a value of
 263 .Li 1 ,
 264 .Li 2 ,
 265 .Li 4 ,
 266 or
 267 .Li 8 .
 268 .Pp
 269 .Fa plusy
 270 is the value
 271 .Li y
 272 in the alignment term
 273 .Dq Li xn + y .
 274 It must have a value between
 275 .Li 0
 276 and
 277 .Li 7 ,
 278 inclusive.
 279 .\"
 280 .Ss inet6_option_next
 281 This function processes the next Hop-by-Hop option or Destination
 282 option in an ancillary data object.
 283 If another option remains to be
 284 processed, the return value of the function is
 285 .Li 0
 286 and
 287 .Fa *tptrp
 288 points to
 289 the 8-bit option type field
 290 .Po
 291 which is followed by the 8-bit option
 292 data length, followed by the option data
 293 .Pc .
 294 If no more options remain
 295 to be processed, the return value is
 296 .Li -1
 297 and
 298 .Fa *tptrp
 299 is
 300 .Dv NULL .
 301 If an error occurs, the return value is
 302 .Li -1
 303 and
 304 .Fa *tptrp
 305 is not
 306 .Dv NULL .
 307 .Pp
 308 .Fa cmsg
 309 is a pointer to
 310 .Li cmsghdr
 311 structure of which
 312 .Li cmsg_level
 313 equals
 314 .Dv IPPROTO_IPV6
 315 and
 316 .Li cmsg_type
 317 equals either
 318 .Dv IPV6_HOPOPTS
 319 or
 320 .Dv IPV6_DSTOPTS .
 321 .Pp
 322 .Fa tptrp
 323 is a pointer to a pointer to an 8-bit byte and
 324 .Fa *tptrp
 325 is used
 326 by the function to remember its place in the ancillary data object
 327 each time the function is called.
 328 The first time this function is
 329 called for a given ancillary data object,
 330 .Fa *tptrp
 331 must be set to
 332 .Dv NULL .
 333 .Pp
 334 Each time this function returns success,
 335 .Fa *tptrp
 336 points to the 8-bit
 337 option type field for the next option to be processed.
 338 .\"
 339 .Ss inet6_option_find
 340 This function is similar to the previously described
 341 .Fn inet6_option_next
 342 function, except this function lets the caller
 343 specify the option type to be searched for, instead of always
 344 returning the next option in the ancillary data object.
 345 .Fa cmsg
 346 is a
 347 pointer to
 348 .Li cmsghdr
 349 structure of which
 350 .Li cmsg_level
 351 equals
 352 .Dv IPPROTO_IPV6
 353 and
 354 .Li cmsg_type
 355 equals either
 356 .Dv IPV6_HOPOPTS
 357 or
 358 .Dv IPV6_DSTOPTS .
 359 .Pp
 360 .Fa tptrp
 361 is a pointer to a pointer to an 8-bit byte and
 362 .Fa *tptrp
 363 is used
 364 by the function to remember its place in the ancillary data object
 365 each time the function is called.
 366 The first time this function is
 367 called for a given ancillary data object,
 368 .Fa *tptrp
 369 must be set to
 370 .Dv NULL .
 371 .Pa
 372 This function starts searching for an option of the specified type
 373 beginning after the value of
 374 .Fa *tptrp .
 375 If an option of the specified
 376 type is located, this function returns
 377 .Li 0
 378 and
 379 .Fa *tptrp
 380 points to the 8-
 381 bit option type field for the option of the specified type.
 382 If an
 383 option of the specified type is not located, the return value is
 384 .Li -1
 385 and
 386 .Fa *tptrp
 387 is
 388 .Dv NULL .
 389 If an error occurs, the return value is
 390 .Li -1
 391 and
 392 .Fa *tptrp
 393 is not
 394 .Dv NULL .
 395 .\"
 396 .Sh DIAGNOSTICS
 397 .Fn inet6_option_init
 398 and
 399 .Fn inet6_option_append
 400 return
 401 .Li 0
 402 on success or
 403 .Li -1
 404 on an error.
 405 .Pp
 406 .Fn inet6_option_alloc
 407 returns
 408 .Dv NULL
 409 on an error.
 410 .Pp
 411 On errors,
 412 .Fn inet6_option_next
 413 and
 414 .Fn inet6_option_find
 415 return
 416 .Li -1
 417 setting
 418 .Fa *tptrp
 419 to non
 420 .Dv NULL
 421 value.
 422 .\"
 423 .Sh EXAMPLES
 424 RFC2292 gives comprehensive examples in chapter 6.
 425 .\"
 426 .Sh SEE ALSO
 427 .Rs
 428 .%A W. Stevens
 429 .%A M. Thomas
 430 .%T "Advanced Sockets API for IPv6"
 431 .%N RFC2292
 432 .%D February 1998
 433 .Re
 434 .Rs
 435 .%A S. Deering
 436 .%A R. Hinden
 437 .%T "Internet Protocol, Version 6 (IPv6) Specification"
 438 .%N RFC2460
 439 .%D December 1998
 440 .Re
 441 .\"
 442 .Sh HISTORY
 443 The implementation first appeared in KAME advanced networking kit.
 444 .\"
 445 .Sh STANDARDS
 446 The functions
 447 are documented in
 448 .Dq Advanced Sockets API for IPv6
 449 .Pq RFC2292 .
 450 .\"
 451 .Sh BUGS
 452 The text was shamelessly copied from RFC2292.