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