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