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