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.5 2006/02/17 19:35:06 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 RFC2292 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 RFC2460.
 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 function returns
 161 .Li 0
 162 if it succeeds or
 163 .Li -1
 164 when an error occurs.
 165 .Pp
 166 The
 167 .Fa cmsg
 168 argument is a pointer to the
 169 .Li cmsghdr
 170 structure that was initialized by a call to
 171 .Fn inet6_option_init .
 172 .Pp
 173 The
 174 .Fa typep
 175 argument is a pointer to the 8-bit option type.
 176 All options are
 177 encoded as type-length-value tuples and it is assumed that
 178 the
 179 .Fa typep
 180 field is immediately followed by the 8-bit option data length field,
 181 which is then followed by the option data.
 182 .Pp
 183 The option types of
 184 .Li 0
 185 and
 186 .Li 1 are reserved for the
 187 .Li Pad1
 188 and
 189 .Li PadN
 190 options respectively.
 191 All other values from
 192 .Li 2
 193 through
 194 .Li 255
 195 are available for applications to use.
 196 .Pp
 197 The option data length, since it is stored in 8 bites, must have a
 198 value between
 199 .Li 0
 200 and
 201 .Li 255 ,
 202 inclusive.
 203 .Pp
 204 The
 205 .Fa multx
 206 argument
 207 is the value
 208 .Li x
 209 in the alignment term
 210 .Dq Li xn + y
 211 and indicates the byte alignment necessary for the data.
 212 Alignments may be specified as
 213 .Li 1 ,
 214 .Li 2 ,
 215 .Li 4 ,
 216 or
 217 .Li 8
 218 bytes, which is no alignment, 16 bit, 32 bit and 64 bit alignments
 219 respectively.
 220 .Pp
 221 The
 222 .Fa plusy
 223 argument
 224 is the value
 225 .Li y
 226 in the alignment term
 227 .Dq Li xn + y
 228 and must have a value between
 229 .Li 0
 230 and
 231 .Li 7 ,
 232 inclusive, indicating the amount of padding that is necessary for an
 233 option.
 234 .\"
 235 .Ss inet6_option_alloc
 236 The
 237 .Fn inet6_option_alloc
 238 function appends a Hop-by-Hop option or a Destination option into an
 239 ancillary data object that has previously been initialized by a call to
 240 .Fn inet6_option_init .
 241 The
 242 .Fn inet6_option_alloc
 243 function returns a pointer to the 8-bit option type field that at the
 244 beginning of the allocated the option on success, or
 245 .Dv NULL
 246 on an error.
 247 .Pp
 248 The difference between the
 249 .Fn inet6_option_alloc
 250 and
 251 .Fn inet6_option_append
 252 functions is that the latter copies the contents of a previously built
 253 option into the ancillary data object while the former returns a
 254 pointer to the place in the data object where the option's TLV must
 255 then be built by the application.
 256 .Pp
 257 The
 258 .Fa cmsg
 259 argument is a pointer to a
 260 .Li cmsghdr
 261 structure that was initialized by
 262 .Fn inet6_option_init .
 263 .Pp
 264 The
 265 .Fa datalen
 266 argument is the value of the option data length byte for this option.
 267 This value is required as an argument to allow the function to
 268 determine if padding must be appended at the end of the option.
 269 (The
 270 .Fn inet6_option_append
 271 function does not need a data length argument
 272 since the option data length must already be stored by the caller)
 273 .Pp
 274 The
 275 .Fa multx
 276 and
 277 .Fa plusy
 278 arguments
 279 are identical to the arguments of the same name described in the
 280 .Fn inet6_option_init
 281 function above.
 282 .\"
 283 .Ss inet6_option_next
 284 The
 285 .Fn inet6_option_next
 286 function is used to process Hop-by-Hop and Destination options that
 287 are present in an ancillary data object.
 288 When an option remains to
 289 be processed, the return value of the
 290 .Fn inet6_option_next
 291 function is
 292 .Li 0
 293 and the
 294 .Fa *tptrp
 295 argument points to the 8-bit option type field, which is followed by
 296 the 8-bit option data length, and then the option data.
 297 When no more
 298 options remain to be processed, the return value is
 299 .Li -1
 300 and
 301 .Fa *tptrp
 302 is
 303 .Dv NULL
 304 and when an error occurs, the return value is
 305 .Li -1
 306 but the
 307 .Fa *tptrp
 308 argument is not
 309 .Dv NULL .
 310 This set of return values allows a program to easily loop through all
 311 the options in an ancillary data object, checking for the error and
 312 end of stream conditions along the way.
 313 .Pp
 314 When a valid option is returned the
 315 .Fa cmsg
 316 argument points to a
 317 .Li cmsghdr
 318 where the
 319 .Li cmsg_level
 320 equals
 321 .Dv IPPROTO_IPV6
 322 and
 323 .Li cmsg_type
 324 is either
 325 .Dv IPV6_HOPOPTS
 326 or
 327 .Dv IPV6_DSTOPTS .
 328 .Pp
 329 The
 330 .Fa tptrp
 331 argument is a pointer to a pointer to an 8-bit byte and
 332 .Fa *tptrp
 333 is used by the function to remember its place in the ancillary data
 334 object each time the function is called.
 335 When the
 336 .Fn inet6_option_next
 337 function is called for the first time on a given ancillary data object,
 338 .Fa *tptrp
 339 must be set to
 340 .Dv NULL .
 341 .Pp
 342 Each time the function returns success,
 343 the
 344 .Fa *tptrp
 345 argument points to the 8-bit option type field for the next option to
 346 be processed.
 347 .\"
 348 .Ss inet6_option_find
 349 The
 350 .Fn inet6_option_find
 351 function allows an application to search for a particular option type
 352 in an ancillary data object.
 353 The
 354 .Fa cmsg
 355 argument is a pointer to
 356 .Li cmsghdr
 357 structure in which the
 358 .Li cmsg_level
 359 element equals
 360 .Dv IPPROTO_IPV6
 361 and the
 362 .Li cmsg_type
 363 element is either
 364 .Dv IPV6_HOPOPTS
 365 or
 366 .Dv IPV6_DSTOPTS .
 367 .Pp
 368 The
 369 .Fa tptrp
 370 argument is handled exactly as in the
 371 .Fn inet6_option_next
 372 function described above.
 373 .Pa
 374 The
 375 .Fn inet6_option_find
 376 function starts searching for an option of the specified type
 377 beginning after the value of
 378 .Fa *tptrp .
 379 .\"
 380 .Sh EXAMPLES
 381 RFC2292 gives comprehensive examples in chapter 6.
 382 .\"
 383 .Sh DIAGNOSTICS
 384 The
 385 .Fn inet6_option_init
 386 and
 387 .Fn inet6_option_append
 388 functions return
 389 .Li 0
 390 on success or
 391 .Li -1
 392 on an error.
 393 .Pp
 394 The
 395 .Fn inet6_option_alloc
 396 function returns
 397 .Dv NULL
 398 on an error.
 399 .Pp
 400 When
 401 .Fn inet6_option_next
 402 or
 403 .Fn inet6_option_find
 404 detect an error they return
 405 .Li -1
 406 setting
 407 .Fa *tptrp
 408 to non
 409 .Dv NULL
 410 value.
 411 .\"
 412 .Sh SEE ALSO
 413 .Rs
 414 .%A W. Stevens
 415 .%A M. Thomas
 416 .%T "Advanced Sockets API for IPv6"
 417 .%N RFC2292
 418 .%D February 1998
 419 .Re
 420 .Rs
 421 .%A S. Deering
 422 .%A R. Hinden
 423 .%T "Internet Protocol, Version 6 (IPv6) Specification"
 424 .%N RFC2460
 425 .%D December 1998
 426 .Re
 427 .\"
 428 .Sh STANDARDS
 429 The functions are documented in
 430 .Dq Advanced Sockets API for IPv6
 431 (RFC2292).
 432 .\"
 433 .Sh HISTORY
 434 The implementation first appeared in KAME advanced networking kit.
 435 .\"