lib/libc/net/inet6_option_space.3

   1 .\"     $KAME: inet6_option_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $
   2 .\"     $FreeBSD: src/lib/libc/net/inet6_option_space.3,v 1.16 2005/01/23 16:02:48 gnn Exp $
   3 .\"     $DragonFly: src/lib/libc/net/inet6_option_space.3,v 1.8 2008/04/20 22:24:53 swildner Exp $
   4 .\"
   5 .\" Copyright (C) 2004 WIDE Project.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the project 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 PROJECT 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 PROJECT 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 .Dd December 23, 2004
  33 .Dt INET6_OPTION_SPACE 3
  34 .Os
  35 .\"
  36 .Sh NAME
  37 .Nm inet6_option_space ,
  38 .Nm inet6_option_init ,
  39 .Nm inet6_option_append ,
  40 .Nm inet6_option_alloc ,
  41 .Nm inet6_option_next ,
  42 .Nm inet6_option_find
  43 .Nd IPv6 Hop-by-Hop and Destination Option Manipulation
  44 .\"
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In sys/types.h
  49 .In 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 Manipulating and parsing IPv6's Hop-by-Hop and Destination options is
  66 complicated by the need to properly align and pad data as well as the
  67 need to manipulate ancillary information that is not part of the data
  68 stream.
  69 RFC 2292 defines a set of functions, which are implemented as
  70 part of the Kame libraries, to support help developers create, change,
  71 and parse Hop-by-Hope and Destination options.
  72 All of the prototypes
  73 for the option functions are defined in the
  74 .In netinet/in.h
  75 header file.
  76 .\"
  77 .Ss inet6_option_space
  78 In order to determine the amount of space necessary to hold any option
  79 the
  80 .Fn inet6_option_space
  81 function is called.
  82 It returns the number of bytes required to hold
  83 an option when it is stored as ancillary data, including the
  84 .Li cmsghdr
  85 structure at the beginning, and any necessary padding at the end.
  86 The
  87 .Li nbytes
  88 argument indicates the size of the structure defining the option,
  89 and must include any pad bytes at the beginning (the value
  90 .Li y
  91 in the alignment term
  92 .Dq Li "xn + y" ) ,
  93 the type byte, the length byte, and the option data.
  94 .Pp
  95 Note: If multiple options are stored in a single ancillary data
  96 object, which is the recommended technique, the
  97 .Fn inet6_option_space
  98 function overestimates the amount of space required by the size of
  99 .Li N-1
 100 .Li cmsghdr
 101 structures, where
 102 .Li N
 103 is the number of options to be stored in the object.
 104 Usually this has
 105 no impact because it is assumed that most Hop-by-Hop and Destination
 106 option headers carry only one option as indicated in appendix B of RFC 2460.
 107 .\"
 108 .Ss inet6_option_init
 109 The
 110 .Fn inet6_option_init
 111 function is called to initialize any ancillary data object that will contain
 112 a Hop-by-Hop or Destination option.
 113 It returns
 114 .Li 0
 115 on success and
 116 .Li -1
 117 when an error occurs.
 118 .Pp
 119 The
 120 .Fa bp
 121 argument points to a previously allocated area of memory which must be
 122 large enough to contain all the arguments that the application indents
 123 to add later via
 124 .Fn inet6_option_append
 125 and
 126 .Fn inet6_option_alloc
 127 routines.
 128 .Pp
 129 The
 130 .Fa cmsgp
 131 argument is a pointer to a pointer to a
 132 .Li cmsghdr
 133 structure.
 134 The
 135 .Fa *cmsgp
 136 argument
 137 points to a
 138 .Li cmsghdr
 139 structure which is constructed by this function and stored in the
 140 area of memory pointed to by
 141 .Fa bp .
 142 .Pp
 143 The
 144 .Fa type
 145 is either
 146 .Dv IPV6_HOPOPTS
 147 or
 148 .Dv IPV6_DSTOPTS
 149 and is stored in the
 150 .Li cmsg_type
 151 member of the
 152 .Li cmsghdr
 153 structure mentioned above.
 154 .\"
 155 .Ss inet6_option_append
 156 This function appends a Hop-by-Hop option or a Destination option into
 157 an ancillary data object previously initialized by a call to
 158 .Fn inet6_option_init .
 159 The
 160 .Fn inet6_option_append
 161 function returns
 162 .Li 0
 163 if it succeeds or
 164 .Li -1
 165 when an error occurs.
 166 .Pp
 167 The
 168 .Fa cmsg
 169 argument is a pointer to the
 170 .Li cmsghdr
 171 structure that was initialized by a call to
 172 .Fn inet6_option_init .
 173 .Pp
 174 The
 175 .Fa typep
 176 argument is a pointer to the 8-bit option type.
 177 All options are
 178 encoded as type-length-value tuples and it is assumed that
 179 the
 180 .Fa typep
 181 field is immediately followed by the 8-bit option data length field,
 182 which is then followed by the option data.
 183 .Pp
 184 The option types of
 185 .Li 0
 186 and
 187 .Li 1 are reserved for the
 188 .Li Pad1
 189 and
 190 .Li PadN
 191 options respectively.
 192 All other values from
 193 .Li 2
 194 through
 195 .Li 255
 196 are available for applications to use.
 197 .Pp
 198 The option data length, since it is stored in 8 bites, must have a
 199 value between
 200 .Li 0
 201 and
 202 .Li 255 ,
 203 inclusive.
 204 .Pp
 205 The
 206 .Fa multx
 207 argument
 208 is the value
 209 .Li x
 210 in the alignment term
 211 .Dq Li xn + y
 212 and indicates the byte alignment necessary for the data.
 213 Alignments may be specified as
 214 .Li 1 ,
 215 .Li 2 ,
 216 .Li 4 ,
 217 or
 218 .Li 8
 219 bytes, which is no alignment, 16 bit, 32 bit and 64 bit alignments
 220 respectively.
 221 .Pp
 222 The
 223 .Fa plusy
 224 argument
 225 is the value
 226 .Li y
 227 in the alignment term
 228 .Dq Li xn + y
 229 and must have a value between
 230 .Li 0
 231 and
 232 .Li 7 ,
 233 inclusive, indicating the amount of padding that is necessary for an
 234 option.
 235 .\"
 236 .Ss inet6_option_alloc
 237 The
 238 .Fn inet6_option_alloc
 239 function appends a Hop-by-Hop option or a Destination option into an
 240 ancillary data object that has previously been initialized by a call to
 241 .Fn inet6_option_init .
 242 The
 243 .Fn inet6_option_alloc
 244 function returns a pointer to the 8-bit option type field that at the
 245 beginning of the allocated the option on success, or
 246 .Dv NULL
 247 on an error.
 248 .Pp
 249 The difference between the
 250 .Fn inet6_option_alloc
 251 and
 252 .Fn inet6_option_append
 253 functions is that the latter copies the contents of a previously built
 254 option into the ancillary data object while the former returns a
 255 pointer to the place in the data object where the option's TLV must
 256 then be built by the application.
 257 .Pp
 258 The
 259 .Fa cmsg
 260 argument is a pointer to a
 261 .Li cmsghdr
 262 structure that was initialized by
 263 .Fn inet6_option_init .
 264 .Pp
 265 The
 266 .Fa datalen
 267 argument is the value of the option data length byte for this option.
 268 This value is required as an argument to allow the function to
 269 determine if padding must be appended at the end of the option.
 270 (The
 271 .Fn inet6_option_append
 272 function does not need a data length argument
 273 since the option data length must already be stored by the caller)
 274 .Pp
 275 The
 276 .Fa multx
 277 and
 278 .Fa plusy
 279 arguments
 280 are identical to the arguments of the same name described in the
 281 .Fn inet6_option_init
 282 function above.
 283 .\"
 284 .Ss inet6_option_next
 285 The
 286 .Fn inet6_option_next
 287 function is used to process Hop-by-Hop and Destination options that
 288 are present in an ancillary data object.
 289 When an option remains to
 290 be processed, the return value of the
 291 .Fn inet6_option_next
 292 function is
 293 .Li 0
 294 and the
 295 .Fa *tptrp
 296 argument points to the 8-bit option type field, which is followed by
 297 the 8-bit option data length, and then the option data.
 298 When no more
 299 options remain to be processed, the return value is
 300 .Li -1
 301 and
 302 .Fa *tptrp
 303 is
 304 .Dv NULL
 305 and when an error occurs, the return value is
 306 .Li -1
 307 but the
 308 .Fa *tptrp
 309 argument is not
 310 .Dv NULL .
 311 This set of return values allows a program to easily loop through all
 312 the options in an ancillary data object, checking for the error and
 313 end of stream conditions along the way.
 314 .Pp
 315 When a valid option is returned the
 316 .Fa cmsg
 317 argument points to a
 318 .Li cmsghdr
 319 where the
 320 .Li cmsg_level
 321 equals
 322 .Dv IPPROTO_IPV6
 323 and
 324 .Li cmsg_type
 325 is either
 326 .Dv IPV6_HOPOPTS
 327 or
 328 .Dv IPV6_DSTOPTS .
 329 .Pp
 330 The
 331 .Fa tptrp
 332 argument is a pointer to a pointer to an 8-bit byte and
 333 .Fa *tptrp
 334 is used by the function to remember its place in the ancillary data
 335 object each time the function is called.
 336 When the
 337 .Fn inet6_option_next
 338 function is called for the first time on a given ancillary data object,
 339 .Fa *tptrp
 340 must be set to
 341 .Dv NULL .
 342 .Pp
 343 Each time the function returns success,
 344 the
 345 .Fa *tptrp
 346 argument points to the 8-bit option type field for the next option to
 347 be processed.
 348 .\"
 349 .Ss inet6_option_find
 350 The
 351 .Fn inet6_option_find
 352 function allows an application to search for a particular option type
 353 in an ancillary data object.
 354 The
 355 .Fa cmsg
 356 argument is a pointer to
 357 .Li cmsghdr
 358 structure in which the
 359 .Li cmsg_level
 360 element equals
 361 .Dv IPPROTO_IPV6
 362 and the
 363 .Li cmsg_type
 364 element is either
 365 .Dv IPV6_HOPOPTS
 366 or
 367 .Dv IPV6_DSTOPTS .
 368 .Pp
 369 The
 370 .Fa tptrp
 371 argument is handled exactly as in the
 372 .Fn inet6_option_next
 373 function described above.
 374 .Pp
 375 The
 376 .Fn inet6_option_find
 377 function starts searching for an option of the specified type
 378 beginning after the value of
 379 .Fa *tptrp .
 380 .\"
 381 .Sh EXAMPLES
 382 RFC 2292 gives comprehensive examples in chapter 6.
 383 .\"
 384 .Sh DIAGNOSTICS
 385 The
 386 .Fn inet6_option_init
 387 and
 388 .Fn inet6_option_append
 389 functions return
 390 .Li 0
 391 on success or
 392 .Li -1
 393 on an error.
 394 .Pp
 395 The
 396 .Fn inet6_option_alloc
 397 function returns
 398 .Dv NULL
 399 on an error.
 400 .Pp
 401 When
 402 .Fn inet6_option_next
 403 or
 404 .Fn inet6_option_find
 405 detect an error they return
 406 .Li -1
 407 setting
 408 .Fa *tptrp
 409 to non
 410 .Dv NULL
 411 value.
 412 .\"
 413 .Sh SEE ALSO
 414 .Rs
 415 .%A W. Stevens
 416 .%A M. Thomas
 417 .%T "Advanced Sockets API for IPv6"
 418 .%N RFC 2292
 419 .%D February 1998
 420 .Re
 421 .Rs
 422 .%A S. Deering
 423 .%A R. Hinden
 424 .%T "Internet Protocol, Version 6 (IPv6) Specification"
 425 .%N RFC 2460
 426 .%D December 1998
 427 .Re
 428 .\"
 429 .Sh STANDARDS
 430 The functions are documented in
 431 .Dq Advanced Sockets API for IPv6
 432 (RFC 2292).
 433 .\"
 434 .Sh HISTORY
 435 The implementation first appeared in KAME advanced networking kit.
 436 .\"