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