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