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