1.\" $OpenBSD: inet6_opt_init.3,v 1.3 2007/05/31 19:19:30 jmc 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: May 31 2007 $ 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. 68.\"This man page describes the functions specified in 69.\"IETF Draft RFC 3542 while the 70.\".Xr inet6_options_space 3 71.\"man page documents the functions defined in RFC 2292. 72.\"It is expected 73.\"that this set of functions will supersede those in RFC 2292 but for 74.\"the time being both APIs are retained. 75These functions use the 76formatting rules specified in Appendix B in RFC 2460, i.e. that the 77largest field is placed last in the option. 78The function prototypes 79for these functions are all contained in the header file 80.Aq Pa netinet/in.h . 81.\" 82.Ss inet6_opt_init 83The 84.Fn inet6_opt_init 85function 86returns the number of bytes needed for an empty 87extension header, one without any options. 88If the 89.Va extbuf 90argument points to a valid section of memory 91then the 92.Fn inet6_opt_init 93function also initializes the extension header's length field. 94When attempting to initialize an extension buffer passed in the 95.Va extbuf 96argument, 97.Fa extlen 98must be a positive multiple of 8 or else the function fails and 99returns \-1 to the caller. 100.\" 101.Ss inet6_opt_append 102The 103.Fn inet6_opt_append 104function can perform different jobs. 105When a valid 106.Fa extbuf 107argument is supplied it appends an option to the extension buffer and 108returns the updated total length as well as a pointer to the newly 109created option in 110.Fa databufp . 111If the value 112of 113.Fa extbuf 114is 115.Dv NULL 116then the 117.Fn inet6_opt_append 118function only reports what the total length would 119be if the option were actually appended. 120The 121.Fa len 122and 123.Fa align 124arguments specify the length of the option and the required data 125alignment which must be used when appending the option. 126The 127.Fa offset 128argument should be the length returned by the 129.Fn inet6_opt_init 130function or a previous call to 131.Fn inet6_opt_append . 132.Pp 133The 134.Fa type 135argument is the 8-bit option type. 136.Pp 137After 138.Fn inet6_opt_append 139has been called, the application can use the buffer pointed to by 140.Fa databufp 141directly, or use 142.Fn inet6_opt_set_val 143to specify the data to be contained in the option. 144.Pp 145Option types of 146.Li 0 147and 148.Li 1 149are reserved for the 150.Li Pad1 151and 152.Li PadN 153options. 154All other values from 2 through 255 may be used by applications. 155.Pp 156The length of the option data is contained in an 8-bit value and so 157may contain any value from 0 through 255. 158.Pp 159The 160.Fa align 161parameter must have a value of 1, 2, 4, or 8 and cannot exceed the 162value of 163.Fa len . 164The alignment values represent no alignment, 16-bit, 32-bit and 64-bit 165alignments respectively. 166.\" 167.Ss inet6_opt_finish 168The 169.Fn inet6_opt_finish 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 . 242.Fa typep , lenp , 243and 244.Fa databufp 245point to the 8-bit option type, the 8-bit option length and the option 246data respectively. 247This function does not return any PAD1 or PADN options. 248When an error occurs or there are no more options the return 249value is \-1. 250.\" 251.Ss inet6_opt_find 252The 253.Fn inet6_opt_find 254function searches the extension buffer for a particular option type, 255passed in through the 256.Fa type 257argument. 258If the option is found then the 259.Fa lenp 260and 261.Fa databufp 262arguments are updated to point to the option's length and data 263respectively. 264.Fa extbuf 265and 266.Fa extlen 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 EXAMPLES 305RFC 3542 gives comprehensive examples in Section 23. 306KAME also provides examples in the 307.Pa advapitest 308directory of its kit. 309.\" 310.Sh DIAGNOSTICS 311All the functions return 312\-1 313on an error. 314.\" 315.Sh SEE ALSO 316.Rs 317.%A W. Stevens 318.%A M. Thomas 319.%A E. Nordmark 320.%A T. Jinmei 321.%T "Advanced Sockets API for IPv6" 322.%N RFC 3542 323.%D October 2002 324.Re 325.Rs 326.%A S. Deering 327.%A R. Hinden 328.%T "Internet Protocol, Version 6 (IPv6) Specification" 329.%N RFC 2460 330.%D December 1998 331.Re 332.Sh STANDARDS 333The functions are documented in 334.Dq Advanced Sockets API for IPv6 335.Pq RFC 3542 . 336.Sh HISTORY 337The implementation first appeared in KAME advanced networking kit. 338.\" 339