1.\" $KAME: inet6_opt_init.3,v 1.7 2004/12/27 05:08:23 itojun Exp $ 2.\" 3.\" Copyright (C) 2004 WIDE Project. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the project nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd February 25, 2023 33.Dt INET6_OPT_INIT 3 34.Os 35.\" 36.Sh NAME 37.Nm inet6_opt_init , 38.Nm inet6_opt_append , 39.Nm inet6_opt_finish , 40.Nm inet6_opt_set_val , 41.Nm inet6_opt_next , 42.Nm inet6_opt_find , 43.Nm inet6_opt_get_val 44.Nd IPv6 Hop-by-Hop and Destination Options manipulation 45.\" 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In netinet/in.h 50.Ft "int" 51.Fn inet6_opt_init "void *extbuf" "socklen_t extlen" 52.Ft "int" 53.Fn inet6_opt_append "void *extbuf" "socklen_t extlen" "int offset" "uint8_t type" "socklen_t len" "uint8_t align" "void **databufp" 54.Ft "int" 55.Fn inet6_opt_finish "void *extbuf" "socklen_t extlen" "int offset" 56.Ft "int" 57.Fn inet6_opt_set_val "void *databuf" "int offset" "void *val" "socklen_t vallen" 58.Ft "int" 59.Fn inet6_opt_next "void *extbuf" "socklen_t extlen" "int offset" "uint8_t *typep" "socklen_t *lenp" "void **databufp" 60.Ft "int" 61.Fn inet6_opt_find "void *extbuf" "socklen_t extlen" "int offset" "uint8_t type" "socklen_t *lenp" "void **databufp" 62.Ft "int" 63.Fn inet6_opt_get_val "void *databuf" "int offset" "void *val" "socklen_t vallen" 64.\" 65.Sh DESCRIPTION 66Building and parsing the Hop-by-Hop and Destination options is 67complicated. 68The advanced sockets API defines a set of functions to 69help applications create and manipulate Hop-by-Hop and Destination 70options. 71This man page describes the functions specified in 72IETF Draft RFC 3542. 73These functions use the 74formatting rules specified in Appendix B in RFC 2460, i.e., that the 75largest field is placed last in the option. 76The function prototypes 77for these functions are all contained in the 78.In netinet/in.h 79header file. 80.\" 81.Ss inet6_opt_init 82The 83.Fn inet6_opt_init 84function 85returns the number of bytes needed for an empty 86extension header, one without any options. 87If the 88.Fa extbuf 89argument points to a valid section of memory 90then the 91.Fn inet6_opt_init 92function also initializes the extension header's length field. 93When attempting to initialize an extension buffer passed in the 94.Fa extbuf 95argument, 96.Fa extlen 97must be a positive multiple of 8 or else the function fails and 98returns \-1 to the caller. 99.\" 100.Ss inet6_opt_append 101The 102.Fn inet6_opt_append 103function can perform two different jobs. 104When a valid 105.Fa extbuf 106argument is supplied it appends an option to the extension buffer and 107returns the updated total length as well as a pointer to the newly 108created option in 109.Fa databufp . 110If the value 111of 112.Fa extbuf 113is 114.Dv NULL 115then the 116.Fn inet6_opt_append 117function only reports what the total length would 118be if the option were actually appended. 119The 120.Fa len 121and 122.Fa align 123arguments specify the length of the option and the required data 124alignment which must be used when appending the option. 125The 126.Fa offset 127argument should be the length returned by the 128.Fn inet6_opt_init 129function or a previous call to 130.Fn inet6_opt_append . 131.Pp 132The 133.Fa type 134argument is the 8-bit option type. 135.Pp 136After 137.Fn inet6_opt_append 138has been called, the application can use the buffer pointed to by 139.Fa databufp 140directly, or use 141.Fn inet6_opt_set_val 142to specify the data to be contained in the option. 143.Pp 144Option types of 145.Li 0 146and 147.Li 1 148are reserved for the 149.Li Pad1 150and 151.Li PadN 152options. 153All other values from 2 through 255 may be used by applications. 154.Pp 155The length of the option data is contained in an 8-bit value and so 156may contain any value from 0 through 255. 157.Pp 158The 159.Fa align 160parameter must have a value of 1, 2, 4, or 8 and cannot exceed the 161value of 162.Fa len . 163The alignment values represent no alignment, 16 bit, 32 bit and 64 bit 164alignments, respectively. 165.\" 166.Ss inet6_opt_finish 167The 168.Fn inet6_opt_finish 169function 170calculates the final padding necessary to make the extension header a 171multiple of 8 bytes, as required by the IPv6 extension header 172specification, and returns the extension header's updated total 173length. 174The 175.Fa offset 176argument should be the length returned by 177.Fn inet6_opt_init 178or 179.Fn inet6_opt_append . 180When 181.Fa extbuf 182is not 183.Dv NULL 184the function also sets up the appropriate padding bytes by inserting a 185Pad1 or PadN option of the proper length. 186.Pp 187If the extension header is too small to contain the proper padding 188then an error of \-1 is returned to the caller. 189.\" 190.Ss inet6_opt_set_val 191The 192.Fn inet6_opt_set_val 193function inserts data items of various sizes into the data portion of 194the option. 195The 196.Fa databuf 197argument is a pointer to memory that was returned by the 198.Fn inet6_opt_append 199call and the 200.Fa offset 201argument specifies where the option should be placed in the 202data buffer. 203The 204.Fa val 205argument points to an area of memory containing the data to be 206inserted into the extension header, and the 207.Fa vallen 208argument indicates how much data to copy. 209.Pp 210The caller should ensure that each field is aligned on its natural 211boundaries as described in Appendix B of RFC 2460. 212.Pp 213The function returns the offset for the next field which is calculated as 214.Fa offset 215+ 216.Fa vallen 217and is used when composing options with multiple fields. 218.\" 219.Ss inet6_opt_next 220The 221.Fn inet6_opt_next 222function parses received extension headers. 223The 224.Fa extbuf 225and 226.Fa extlen 227arguments specify the location and length of the extension header 228being parsed. 229The 230.Fa offset 231argument should either be zero, for the first option, or the length value 232returned by a previous call to 233.Fn inet6_opt_next 234or 235.Fn inet6_opt_find . 236The return value specifies the position where to continue scanning the 237extension buffer. 238The option is returned in the arguments 239.Fa typep , lenp , 240and 241.Fa databufp , 242which 243point to the 8-bit option type, the 8-bit option length and the option 244data, respectively. 245This function does not return any PAD1 or PADN options. 246When an error occurs or there are no more options, the return 247value is \-1. 248.\" 249.Ss inet6_opt_find 250The 251.Fn inet6_opt_find 252function searches the extension buffer for a particular option type, 253passed in through the 254.Fa type 255argument. 256If the option is found then the 257.Fa lenp 258and 259.Fa databufp 260arguments are updated to point to the option's length and data, 261respectively. 262The 263.Fa extbuf 264and 265.Fa extlen 266arguments 267must point to a valid extension buffer and give its length. 268The 269.Fa offset 270argument can be used to search from a location anywhere in the 271extension header. 272.Ss inet6_opt_get_val 273The 274.Fn inet6_opt_get_val 275function extracts data items of various sizes in the data portion of 276the option. 277The 278.Fa databuf 279is a pointer returned by the 280.Fn inet6_opt_next 281or 282.Fn inet6_opt_find 283functions. 284The 285.Fa val 286argument points to where the data will be extracted. 287The 288.Fa offset 289argument specifies from where in the data portion of the option the 290value should be extracted; the first byte of option data is specified 291by an offset of zero. 292.Pp 293It is expected that each field is aligned on its natural boundaries as 294described in Appendix B of RFC 2460. 295.Pp 296The function returns the offset for the next field 297by calculating 298.Fa offset 299+ 300.Fa vallen 301which can be used when extracting option content with multiple fields. 302Robust receivers must verify alignment before calling this function. 303.\" 304.Sh RETURN VALUES 305All the functions return 306\-1 307on an error. 308.\" 309.Sh EXAMPLES 310RFC 3542 gives comprehensive examples in Section 22. 311.Pp 312KAME also provides examples in the 313.Pa advapitest 314directory of its kit. 315.\" 316.Sh SEE ALSO 317.Rs 318.%A W. Stevens 319.%A M. Thomas 320.%A E. Nordmark 321.%A T. Jinmei 322.%T "Advanced Sockets API for IPv6" 323.%N RFC 3542 324.%D October 2002 325.Re 326.Rs 327.%A S. Deering 328.%A R. Hinden 329.%T "Internet Protocol, Version 6 (IPv6) Specification" 330.%N RFC 2460 331.%D December 1998 332.Re 333.Sh STANDARDS 334The functions are documented in 335.Dq Advanced Sockets API for IPv6 336.Pq RFC 3542 . 337.\" 338.Sh HISTORY 339The implementation first appeared in KAME advanced networking kit. 340