1.\" $NetBSD: inet6_option_space.3,v 1.18 2022/12/04 01:29:32 uwe 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. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd December 10, 1999 32.Dt INET6_OPTION_SPACE 3 33.Os 34.\" 35.Sh NAME 36.Nm inet6_option_space , 37.Nm inet6_option_init , 38.Nm inet6_option_append , 39.Nm inet6_option_alloc , 40.Nm inet6_option_next , 41.Nm inet6_option_find 42.Nd IPv6 Hop-by-Hop and Destination Options manipulation 43.\" 44.Sh SYNOPSIS 45.In netinet/in.h 46.Ft "int" 47.Fn inet6_option_space "int nbytes" 48.Ft "int" 49.Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type" 50.Ft "int" 51.Fn inet6_option_append "struct cmsghdr *cmsg" "const uint8_t *typep" "int multx" "int plusy" 52.Ft "uint8_t *" 53.Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy" 54.Ft "int" 55.Fn inet6_option_next "const struct cmsghdr *cmsg" "uint8_t **tptrp" 56.Ft "int" 57.Fn inet6_option_find "const struct cmsghdr *cmsg" "uint8_t **tptrp" "int type" 58.\" 59.Sh DESCRIPTION 60.\" 61Building and parsing the Hop-by-Hop and Destination options is 62complicated due to alignment constraints, padding and 63ancillary data manipulation. 64RFC 2292 defines a set of functions to help the application. 65The function prototypes for 66these functions are all in the 67.In netinet/in.h 68header. 69.\" 70.Ss inet6_option_space 71.Fn inet6_option_space 72returns the number of bytes required to hold an option when it is stored as 73ancillary data, including the 74.Li cmsghdr 75structure at the beginning, 76and any padding at the end 77.Po 78to make its size a multiple of 8 bytes 79.Pc . 80The argument is the size of the structure defining the option, 81which must include any pad bytes at the beginning 82.Po 83the value 84.Li y 85in the alignment term 86.Dq Li xn + y 87.Pc , 88the type byte, the length byte, and the option data. 89.Pp 90Note: If multiple options are stored in a single ancillary data 91object, which is the recommended technique, this function 92overestimates the amount of space required by the size of 93.Li N-1 94.Li cmsghdr 95structures, 96where 97.Li N 98is the number of options to be stored in the object. 99This is of little consequence, since it is assumed that most 100Hop-by-Hop option headers and Destination option headers carry only 101one option 102.Pq appendix B of [RFC 2460] . 103.\" 104.Ss inet6_option_init 105.Fn inet6_option_init 106is called once per ancillary data object that will 107contain either Hop-by-Hop or Destination options. 108It returns 109.Li 0 110on success or 111.Li -1 112on an error. 113.Pp 114.Fa bp 115is a pointer to previously allocated space that will contain the 116ancillary data object. 117It must be large enough to contain all the 118individual options to be added by later calls to 119.Fn inet6_option_append 120and 121.Fn inet6_option_alloc . 122.Pp 123.Fa cmsgp 124is a pointer to a pointer to a 125.Li cmsghdr 126structure. 127.Fa *cmsgp 128is initialized by this function to point to the 129.Li cmsghdr 130structure constructed by this function in the buffer pointed to by 131.Fa bp . 132.Pp 133.Fa type 134is either 135.Dv IPV6_HOPOPTS 136or 137.Dv IPV6_DSTOPTS . 138This 139.Fa type 140is stored in the 141.Li cmsg_type 142member of the 143.Li cmsghdr 144structure pointed to by 145.Fa *cmsgp . 146.\" 147.Ss inet6_option_append 148This function appends a Hop-by-Hop option or a Destination option 149into an ancillary data object that has been initialized by 150.Fn inet6_option_init . 151This function returns 152.Li 0 153if it succeeds or 154.Li -1 155on an error. 156.Pp 157.Fa cmsg 158is a pointer to the 159.Li cmsghdr 160structure that must have been 161initialized by 162.Fn inet6_option_init . 163.Pp 164.Fa typep 165is a pointer to the 8-bit option type. 166It is assumed that this 167field is immediately followed by the 8-bit option data length field, 168which is then followed immediately by the option data. 169The caller 170initializes these three fields 171.Pq the type-length-value, or TLV 172before calling this function. 173.Pp 174The option type must have a value from 175.Li 2 176to 177.Li 255 , 178inclusive. 179.Po 180.Li 0 181and 182.Li 1 183are reserved for the 184.Li Pad1 185and 186.Li PadN 187options, respectively. 188.Pc 189.Pp 190The option data length must have a value between 191.Li 0 192and 193.Li 255 , 194inclusive, and is the length of the option data that follows. 195.Pp 196.Fa multx 197is the value 198.Li x 199in the alignment term 200.Dq Li xn + y . 201It must have a value of 202.Li 1 , 203.Li 2 , 204.Li 4 , 205or 206.Li 8 . 207.Pp 208.Fa plusy 209is the value 210.Li y 211in the alignment term 212.Dq Li xn + y . 213It must have a value between 214.Li 0 215and 216.Li 7 , 217inclusive. 218.\" 219.Ss inet6_option_alloc 220This function appends a Hop-by-Hop option or a Destination option 221into an ancillary data object that has been initialized by 222.Fn inet6_option_init . 223This function returns a pointer to the 8-bit 224option type field that starts the option on success, or 225.Dv NULL 226on an error. 227.Pp 228The difference between this function and 229.Fn inet6_option_append 230is that the latter copies the contents of a previously built option into 231the ancillary data object while the current function returns a 232pointer to the space in the data object where the option's TLV must 233then be built by the caller. 234.Pp 235.Fa cmsg 236is a pointer to the 237.Li cmsghdr 238structure that must have been 239initialized by 240.Fn inet6_option_init . 241.Pp 242.Fa datalen 243is the value of the option data length byte for this option. 244This value is required as an argument to allow the function to 245determine if padding must be appended at the end of the option. 246.Po 247The 248.Fn inet6_option_append 249function does not need a data length argument 250since the option data length must already be stored by the caller. 251.Pc 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.Po 287which is followed by the 8-bit option 288data length, followed by the option data 289.Pc . 290If no more options remain 291to be processed, the return value is 292.Li -1 293and 294.Fa *tptrp 295is 296.Dv NULL . 297If an error occurs, the return value is 298.Li -1 299and 300.Fa *tptrp 301is not 302.Dv NULL . 303.Pp 304.Fa cmsg 305is a pointer to 306.Li cmsghdr 307structure of which 308.Li cmsg_level 309equals 310.Dv IPPROTO_IPV6 311and 312.Li cmsg_type 313equals either 314.Dv IPV6_HOPOPTS 315or 316.Dv IPV6_DSTOPTS . 317.Pp 318.Fa tptrp 319is a pointer to a pointer to an 8-bit byte and 320.Fa *tptrp 321is used 322by the function to remember its place in the ancillary data object 323each time the function is called. 324The first time this function is 325called for a given ancillary data object, 326.Fa *tptrp 327must be set to 328.Dv NULL . 329.Pp 330Each time this function returns success, 331.Fa *tptrp 332points to the 8-bit 333option type field for the next option to be processed. 334.\" 335.Ss inet6_option_find 336This function is similar to the previously described 337.Fn inet6_option_next 338function, except this function lets the caller 339specify the option type to be searched for, instead of always 340returning the next option in the ancillary data object. 341.Fa cmsg 342is a 343pointer to 344.Li cmsghdr 345structure of which 346.Li cmsg_level 347equals 348.Dv IPPROTO_IPV6 349and 350.Li cmsg_type 351equals either 352.Dv IPV6_HOPOPTS 353or 354.Dv IPV6_DSTOPTS . 355.Pp 356.Fa tptrp 357is a pointer to a pointer to an 8-bit byte and 358.Fa *tptrp 359is used 360by the function to remember its place in the ancillary data object 361each time the function is called. 362The first time this function is 363called for a given ancillary data object, 364.Fa *tptrp 365must be set to 366.Dv NULL . 367.Pa 368This function starts searching for an option of the specified type 369beginning after the value of 370.Fa *tptrp . 371If an option of the specified 372type is located, this function returns 373.Li 0 374and 375.Fa *tptrp 376points to the 8- 377bit option type field for the option of the specified type. 378If an 379option of the specified type is not located, the return value is 380.Li -1 381and 382.Fa *tptrp 383is 384.Dv NULL . 385If an error occurs, the return value is 386.Li -1 387and 388.Fa *tptrp 389is not 390.Dv NULL . 391.\" 392.Sh EXAMPLES 393RFC 2292 gives comprehensive examples in chapter 6. 394.\" 395.Sh RETURN VALUES 396.Fn inet6_option_init 397and 398.Fn inet6_option_append 399return 400.Li 0 401on success or 402.Li -1 403on an error. 404.Pp 405.Fn inet6_option_alloc 406returns 407.Dv NULL 408on an error. 409.Pp 410On errors, 411.Fn inet6_option_next 412and 413.Fn inet6_option_find 414return 415.Li -1 416setting 417.Fa *tptrp 418to non 419.Dv NULL 420value. 421.\" 422.Sh SEE ALSO 423.Rs 424.%A W. Stevens 425.%A M. Thomas 426.%T "Advanced Sockets API for IPv6" 427.%N RFC 2292 428.%D February 1998 429.Re 430.Rs 431.%A S. Deering 432.%A R. Hinden 433.%T "Internet Protocol, Version 6 (IPv6) Specification" 434.%N RFC 2460 435.%D December 1998 436.Re 437.\" 438.Sh STANDARDS 439The functions 440are documented in 441.Dq Advanced Sockets API for IPv6 442.Pq RFC 2292 . 443.\" 444.Sh HISTORY 445The implementation first appeared in KAME advanced networking kit. 446.\" 447.Sh BUGS 448The text was shamelessly copied from RFC 2292. 449