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