1.\" $NetBSD: inet6_option_space.3,v 1.6 2002/02/07 07:00:21 ross Exp $ 2.\" $KAME: inet6_option_space.3,v 1.7 2000/05/17 14:32:13 itojun Exp $ 3.\" 4.\" Copyright (c) 1983, 1987, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.Dd December 10, 1999 36.Dt INET6_OPTION_SPACE 3 37.Os 38.\" 39.Sh NAME 40.Nm inet6_option_space , 41.Nm inet6_option_init , 42.Nm inet6_option_append , 43.Nm inet6_option_alloc , 44.Nm inet6_option_next , 45.Nm inet6_option_find 46.Nd IPv6 Hop-by-Hop and Destination Options manipulation 47.\" 48.Sh SYNOPSIS 49.Fd #include \*[Lt]netinet/in.h\*[Gt] 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.\" 65Building and parsing the Hop-by-Hop and Destination options is 66complicated due to alignment constranints, padding and 67ancillary data manipulation. 68RFC2292 defines a set of functions to help the application. 69The function prototypes for 70these functions are all in the 71.Aq Li netinet/in.h 72header. 73.\" 74.Ss inet6_option_space 75.Fn inet6_option_space 76returns the number of bytes required to hold an option when it is stored as 77ancillary data, including the 78.Li cmsghdr 79structure at the beginning, 80and any padding at the end 81.Po 82to make its size a multiple of 8 bytes 83.Pc . 84The argument is the size of the structure defining the option, 85which must include any pad bytes at the beginning 86.Po 87the value 88.Li y 89in the alignment term 90.Dq Li xn + y 91.Pc , 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.Pq 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.Pq 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.Po 184.Li 0 185and 186.Li 1 187are reserved for the 188.Li Pad1 189and 190.Li PadN 191options, respectively. 192.Pc 193.Pp 194The option data length must have a value between 195.Li 0 196and 197.Li 255 , 198inclusive, and is the length of the option data that follows. 199.Pp 200.Fa multx 201is the value 202.Li x 203in the alignment term 204.Dq Li xn + y . 205It must have a value of 206.Li 1 , 207.Li 2 , 208.Li 4 , 209or 210.Li 8 . 211.Pp 212.Fa plusy 213is the value 214.Li y 215in the alignment term 216.Dq Li xn + y . 217It must have a value between 218.Li 0 219and 220.Li 7 , 221inclusive. 222.\" 223.Ss inet6_option_alloc 224This function appends a Hop-by-Hop option or a Destination option 225into an ancillary data object that has been initialized by 226.Fn inet6_option_init . 227This function returns a pointer to the 8-bit 228option type field that starts the option on success, or 229.Dv NULL 230on an error. 231.Pp 232The difference between this function and 233.Fn inet6_option_append 234is that the latter copies the contents of a previously built option into 235the ancillary data object while the current function returns a 236pointer to the space in the data object where the option's TLV must 237then be built by the caller. 238.Pp 239.Fa cmsg 240is a pointer to the 241.Li cmsghdr 242structure that must have been 243initialized by 244.Fn inet6_option_init . 245.Pp 246.Fa datalen 247is the value of the option data length byte for this option. 248This value is required as an argument to allow the function to 249determine if padding must be appended at the end of the option. 250.Po 251The 252.Fn inet6_option_append 253function does not need a data length argument 254since the option data length must already be stored by the caller. 255.Pc 256.Pp 257.Fa multx 258is the value 259.Li x 260in the alignment term 261.Dq Li xn + y . 262It must have a value of 263.Li 1 , 264.Li 2 , 265.Li 4 , 266or 267.Li 8 . 268.Pp 269.Fa plusy 270is the value 271.Li y 272in the alignment term 273.Dq Li xn + y . 274It must have a value between 275.Li 0 276and 277.Li 7 , 278inclusive. 279.\" 280.Ss inet6_option_next 281This function processes the next Hop-by-Hop option or Destination 282option in an ancillary data object. 283If another option remains to be 284processed, the return value of the function is 285.Li 0 286and 287.Fa *tptrp 288points to 289the 8-bit option type field 290.Po 291which is followed by the 8-bit option 292data length, followed by the option data 293.Pc . 294If no more options remain 295to be processed, the return value is 296.Li -1 297and 298.Fa *tptrp 299is 300.Dv NULL . 301If an error occurs, the return value is 302.Li -1 303and 304.Fa *tptrp 305is not 306.Dv NULL . 307.Pp 308.Fa cmsg 309is a pointer to 310.Li cmsghdr 311structure of which 312.Li cmsg_level 313equals 314.Dv IPPROTO_IPV6 315and 316.Li cmsg_type 317equals either 318.Dv IPV6_HOPOPTS 319or 320.Dv IPV6_DSTOPTS . 321.Pp 322.Fa tptrp 323is a pointer to a pointer to an 8-bit byte and 324.Fa *tptrp 325is used 326by the function to remember its place in the ancillary data object 327each time the function is called. 328The first time this function is 329called for a given ancillary data object, 330.Fa *tptrp 331must be set to 332.Dv NULL . 333.Pp 334Each time this function returns success, 335.Fa *tptrp 336points to the 8-bit 337option type field for the next option to be processed. 338.\" 339.Ss inet6_option_find 340This function is similar to the previously described 341.Fn inet6_option_next 342function, except this function lets the caller 343specify the option type to be searched for, instead of always 344returning the next option in the ancillary data object. 345.Fa cmsg 346is a 347pointer to 348.Li cmsghdr 349structure of which 350.Li cmsg_level 351equals 352.Dv IPPROTO_IPV6 353and 354.Li cmsg_type 355equals either 356.Dv IPV6_HOPOPTS 357or 358.Dv IPV6_DSTOPTS . 359.Pp 360.Fa tptrp 361is a pointer to a pointer to an 8-bit byte and 362.Fa *tptrp 363is used 364by the function to remember its place in the ancillary data object 365each time the function is called. 366The first time this function is 367called for a given ancillary data object, 368.Fa *tptrp 369must be set to 370.Dv NULL . 371.Pa 372This function starts searching for an option of the specified type 373beginning after the value of 374.Fa *tptrp . 375If an option of the specified 376type is located, this function returns 377.Li 0 378and 379.Fa *tptrp 380points to the 8- 381bit option type field for the option of the specified type. 382If an 383option of the specified type is not located, the return value is 384.Li -1 385and 386.Fa *tptrp 387is 388.Dv NULL . 389If an error occurs, the return value is 390.Li -1 391and 392.Fa *tptrp 393is not 394.Dv NULL . 395.\" 396.Sh EXAMPLES 397RFC2292 gives comprehensive examples in chapter 6. 398.\" 399.Sh DIAGNOSTICS 400.Fn inet6_option_init 401and 402.Fn inet6_option_append 403return 404.Li 0 405on success or 406.Li -1 407on an error. 408.Pp 409.Fn inet6_option_alloc 410returns 411.Dv NULL 412on an error. 413.Pp 414On errors, 415.Fn inet6_option_next 416and 417.Fn inet6_option_find 418return 419.Li -1 420setting 421.Fa *tptrp 422to non 423.Dv NULL 424value. 425.\" 426.Sh SEE ALSO 427.Rs 428.%A W. Stevens 429.%A M. Thomas 430.%T "Advanced Sockets API for IPv6" 431.%N RFC2292 432.%D February 1998 433.Re 434.Rs 435.%A S. Deering 436.%A R. Hinden 437.%T "Internet Protocol, Version 6 (IPv6) Specification" 438.%N RFC2460 439.%D December 1998 440.Re 441.\" 442.Sh STANDARDS 443The functions 444are documented in 445.Dq Advanced Sockets API for IPv6 446.Pq RFC2292 . 447.\" 448.Sh HISTORY 449The implementation first appeared in KAME advanced networking kit. 450.\" 451.Sh BUGS 452The text was shamelessly copied from RFC2292. 453