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