1.\" $OpenBSD: inet6_opt_init.3,v 1.6 2014/01/21 03:15:45 schwarze Exp $ 2.\" $KAME: inet6_opt_init.3,v 1.7 2004/12/27 05:08:23 itojun Exp $ 3.\" 4.\" Copyright (C) 2004 WIDE Project. 5.\" 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 project 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 PROJECT 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 PROJECT 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 $Mdocdate: January 21 2014 $ 32.Dt INET6_OPT_INIT 3 33.Os 34.\" 35.Sh NAME 36.Nm inet6_opt_init , 37.Nm inet6_opt_append , 38.Nm inet6_opt_finish , 39.Nm inet6_opt_set_val , 40.Nm inet6_opt_next , 41.Nm inet6_opt_find , 42.Nm inet6_opt_get_val 43.Nd IPv6 Hop-by-Hop and Destination Options manipulation 44.\" 45.Sh SYNOPSIS 46.In netinet/in.h 47.Ft "int" 48.Fn inet6_opt_init "void *extbuf" "socklen_t extlen" 49.Ft "int" 50.Fn inet6_opt_append "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t len" "u_int8_t align" "void **databufp" 51.Ft "int" 52.Fn inet6_opt_finish "void *extbuf" "socklen_t extlen" "int offset" 53.Ft "int" 54.Fn inet6_opt_set_val "void *databuf" "int offset" "void *val" "socklen_t vallen" 55.Ft "int" 56.Fn inet6_opt_next "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t *typep" "socklen_t *lenp" "void **databufp" 57.Ft "int" 58.Fn inet6_opt_find "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t *lenp" "void **databufp" 59.Ft "int" 60.Fn inet6_opt_get_val "void *databuf" "socklen_t offset" "void *val" "socklen_t vallen" 61.\" 62.Sh DESCRIPTION 63Building and parsing the Hop-by-Hop and Destination options is 64complicated. 65The advanced sockets API defines a set of functions to 66help applications create and manipulate Hop-by-Hop and Destination 67options. 68These functions use the 69formatting rules specified in Appendix B in RFC 2460, i.e. that the 70largest field is placed last in the option. 71The function prototypes 72for these functions are all contained in the header file 73.In netinet/in.h . 74.\" 75.Ss inet6_opt_init 76The 77.Fn inet6_opt_init 78function 79returns the number of bytes needed for an empty 80extension header, one without any options. 81If the 82.Va extbuf 83argument points to a valid section of memory 84then the 85.Fn inet6_opt_init 86function also initializes the extension header's length field. 87When attempting to initialize an extension buffer passed in the 88.Va extbuf 89argument, 90.Fa extlen 91must be a positive multiple of 8 or else the function fails and 92returns \-1 to the caller. 93.\" 94.Ss inet6_opt_append 95The 96.Fn inet6_opt_append 97function can perform different jobs. 98When a valid 99.Fa extbuf 100argument is supplied it appends an option to the extension buffer and 101returns the updated total length as well as a pointer to the newly 102created option in 103.Fa databufp . 104If the value 105of 106.Fa extbuf 107is 108.Dv NULL 109then the 110.Fn inet6_opt_append 111function only reports what the total length would 112be if the option were actually appended. 113The 114.Fa len 115and 116.Fa align 117arguments specify the length of the option and the required data 118alignment which must be used when appending the option. 119The 120.Fa offset 121argument should be the length returned by the 122.Fn inet6_opt_init 123function or a previous call to 124.Fn inet6_opt_append . 125.Pp 126The 127.Fa type 128argument is the 8-bit option type. 129.Pp 130After 131.Fn inet6_opt_append 132has been called, the application can use the buffer pointed to by 133.Fa databufp 134directly, or use 135.Fn inet6_opt_set_val 136to specify the data to be contained in the option. 137.Pp 138Option types of 139.Li 0 140and 141.Li 1 142are reserved for the 143.Li Pad1 144and 145.Li PadN 146options. 147All other values from 2 through 255 may be used by applications. 148.Pp 149The length of the option data is contained in an 8-bit value and so 150may contain any value from 0 through 255. 151.Pp 152The 153.Fa align 154parameter must have a value of 1, 2, 4, or 8 and cannot exceed the 155value of 156.Fa len . 157The alignment values represent no alignment, 16-bit, 32-bit and 64-bit 158alignments respectively. 159.\" 160.Ss inet6_opt_finish 161The 162.Fn inet6_opt_finish 163calculates the final padding necessary to make the extension header a 164multiple of 8 bytes, as required by the IPv6 extension header 165specification, and returns the extension header's updated total 166length. 167The 168.Fa offset 169argument should be the length returned by 170.Fn inet6_opt_init 171or 172.Fn inet6_opt_append . 173When 174.Fa extbuf 175is not 176.Dv NULL 177the function also sets up the appropriate padding bytes by inserting a 178Pad1 or PadN option of the proper length. 179.Pp 180If the extension header is too small to contain the proper padding 181then an error of \-1 is returned to the caller. 182.\" 183.Ss inet6_opt_set_val 184The 185.Fn inet6_opt_set_val 186function inserts data items of various sizes into the data portion of 187the option. 188The 189.Fa databuf 190argument is a pointer to memory that was returned by the 191.Fn inet6_opt_append 192call and the 193.Fa offset 194argument specifies where the option should be placed in the 195data buffer. 196The 197.Fa val 198argument points to an area of memory containing the data to be 199inserted into the extension header, and the 200.Fa vallen 201argument indicates how much data to copy. 202.Pp 203The caller should ensure that each field is aligned on its natural 204boundaries as described in Appendix B of RFC 2460. 205.Pp 206The function returns the offset for the next field which is calculated as 207.Fa offset 208+ 209.Fa vallen 210and is used when composing options with multiple fields. 211.\" 212.Ss inet6_opt_next 213The 214.Fn inet6_opt_next 215function parses received extension headers. 216The 217.Fa extbuf 218and 219.Fa extlen 220arguments specify the location and length of the extension header 221being parsed. 222The 223.Fa offset 224argument should either be zero, for the first option, or the length value 225returned by a previous call to 226.Fn inet6_opt_next 227or 228.Fn inet6_opt_find . 229The return value specifies the position where to continue scanning the 230extension buffer. 231The option is returned in the arguments 232.Fa typep , lenp , 233and 234.Fa databufp . 235.Fa typep , lenp , 236and 237.Fa databufp 238point to the 8-bit option type, the 8-bit option length and the option 239data respectively. 240This function does not return any PAD1 or PADN options. 241When an error occurs or there are no more options the return 242value is \-1. 243.\" 244.Ss inet6_opt_find 245The 246.Fn inet6_opt_find 247function searches the extension buffer for a particular option type, 248passed in through the 249.Fa type 250argument. 251If the option is found then the 252.Fa lenp 253and 254.Fa databufp 255arguments are updated to point to the option's length and data 256respectively. 257.Fa extbuf 258and 259.Fa extlen 260must point to a valid extension buffer and give its length. 261The 262.Fa offset 263argument can be used to search from a location anywhere in the 264extension header. 265.Ss inet6_opt_get_val 266The 267.Fn inet6_opt_get_val 268function extracts data items of various sizes in the data portion of 269the option. 270The 271.Fa databuf 272is a pointer returned by the 273.Fn inet6_opt_next 274or 275.Fn inet6_opt_find 276functions. 277The 278.Fa val 279argument points to where the data will be extracted. 280The 281.Fa offset 282argument specifies from where in the data portion of the option the 283value should be extracted; the first byte of option data is specified 284by an offset of zero. 285.Pp 286It is expected that each field is aligned on its natural boundaries as 287described in Appendix B of RFC 2460. 288.Pp 289The function returns the offset for the next field 290by calculating 291.Fa offset 292+ 293.Fa vallen 294which can be used when extracting option content with multiple fields. 295Robust receivers must verify alignment before calling this function. 296.\" 297.Sh EXAMPLES 298RFC 3542 gives comprehensive examples in Section 23. 299KAME also provides examples in the 300.Pa advapitest 301directory of its kit. 302.\" 303.Sh DIAGNOSTICS 304All the functions return 305\-1 306on an error. 307.\" 308.Sh STANDARDS 309.Rs 310.%A S. Deering 311.%A R. Hinden 312.%D December 1998 313.%R RFC 2460 314.%T Internet Protocol, Version 6 (IPv6) Specification 315.Re 316.Pp 317.Rs 318.%A W. Stevens 319.%A M. Thomas 320.%A E. Nordmark 321.%A T. Jinmei 322.%D May 2003 323.%R RFC 3542 324.%T Advanced Sockets Application Program Interface (API) for IPv6 325.Re 326.Sh HISTORY 327The implementation first appeared in KAME advanced networking kit. 328.\" 329