1.\" $KAME: inet6_opt_init.3,v 1.5 2002/10/17 14:13:47 jinmei Exp $ 2.\" 3.\" Copyright (C) 2000 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 5, 2000 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" "socklen_t offset" "void *val" "socklen_t vallen" 62.\" 63.Sh DESCRIPTION 64Building and parsing the Hop-by-Hop and Destination options is 65complicated. 66The advanced API therefore defines a set 67of functions to help applications. 68These functions assume the 69formatting rules specified in Appendix B in RFC2460, i.e., that the 70largest field is placed last in the option. 71The function prototypes for 72these functions are all in the 73.In netinet/in.h 74header. 75.\" 76.Ss inet6_opt_init 77The 78.Fn inet6_opt_init 79function 80returns the number of bytes needed for the empty 81extension header, i.e., without any options. 82If 83.Va extbuf 84is not 85.Dv NULL 86it also initializes the extension header to have the correct length 87field. 88In that case if the 89.Fa extlen 90value is not a positive 91(i.e., non-zero) 92multiple of 8 the function fails and returns \-1. 93.\" 94.Ss inet6_opt_append 95The 96.Fn inet6_opt_append 97function 98returns the updated total length taking into account 99adding an option with length 100.Fa len 101and alignment 102.Fa align . 103The 104.Fa offset 105argument 106should be the length returned by 107.Fn inet6_opt_init 108or a previous 109.Fn inet6_opt_append . 110If 111.Fa extbuf 112is not 113.Dv NULL 114then, in addition to returning the length, 115the function inserts any needed pad option, initializes the option 116(setting the type and length fields) 117and returns a pointer to the location for the option content in 118.Fa databufp . 119.Pp 120The 121.Fa type 122argument 123is the 8-bit option type. 124The 125.Fa len 126argument 127is the length of the option data 128(i.e., excluding the option type and option length fields). 129.Pp 130Once 131.Fn inet6_opt_append 132has been called, the application can use the 133databuf directly, or use 134.Fn inet6_opt_set_val 135to specify the content of the option. 136.Pp 137The option type must have a value from 2 to 255, inclusive. 138(0 and 1 are reserved for the Pad1 and PadN options, respectively.) 139.Pp 140The option data length must have a value between 0 and 255, 141inclusive, and is the length of the option data that follows. 142.Pp 143The 144.Fa align 145parameter must have a value of 1, 2, 4, or 8. 146The align value can not exceed the value of 147.Fa len . 148.\" 149.Ss inet6_opt_finish 150The 151.Fn inet6_opt_finish 152function 153returns the updated total length 154taking into account the final padding of the extension header to make 155it a multiple of 8 bytes. 156The 157.Fa offset 158argument 159should be the length returned by 160.Fn inet6_opt_init 161or 162.Fn inet6_opt_append . 163If 164.Fa extbuf 165is not 166.Dv NULL 167the function also 168initializes the option by inserting a Pad1 or PadN option of the 169proper length. 170.Pp 171If the necessary pad does not fit in the extension header buffer the 172function returns \-1. 173.\" 174.Ss inet6_opt_set_val 175The 176.Fn inet6_opt_set_val 177function 178inserts data items of various sizes in the data portion of the option. 179The 180.Fa databuf 181argument 182should be a pointer returned by 183.Fn inet6_opt_append . 184The 185.Fa val 186argument 187should point to the data to be 188inserted. 189The 190.Fa offset 191argument 192specifies where in the data portion of the option 193the value should be inserted; the first byte after the option type 194and length is accessed by specifying an offset of zero. 195.Pp 196The caller should ensure that each field is aligned on its natural 197boundaries as described in Appendix B of RFC2460, but the function 198must not rely on the caller's behavior. 199Even when the alignment requirement is not satisfied, 200the function should just copy the data as required. 201.Pp 202The function returns the offset for the next field 203(i.e., 204.Fa offset 205+ 206.Fa vallen ) 207which can be used when composing option content with multiple fields. 208.\" 209.Ss inet6_opt_next 210The 211.Fn inet6_opt_next 212function 213parses received extension headers returning the next 214option. 215The 216.Fa extbuf 217and 218.Fa extlen 219arguments specify the extension header. 220The 221.Fa offset 222argument 223should either be zero (for the first option), or the length returned 224by a previous call to 225.Fn inet6_opt_next 226or 227.Fn inet6_opt_find . 228It specifies the position where to continue scanning the extension 229buffer. 230The next option is returned by updating 231.Fa typep , lenp , 232and 233.Fa databufp . 234This function returns the updated 235.Dq previous 236length 237computed by advancing past the option that was returned. 238This returned 239.Dq previous 240length can then be passed to subsequent calls to 241.Fn inet6_opt_next . 242This function does not return any PAD1 or PADN options. 243When there are no more options the return value is \-1. 244.\" 245.Ss inet6_opt_get_val 246The 247.Fn inet6_opt_get_val 248function extracts data items of various sizes 249in the data portion of the option. 250The 251.Fa databuf 252argument 253should be a pointer returned by 254.Fn inet6_opt_next 255or 256.Fn inet6_opt_find . 257The 258.Fa val 259argument 260should point to the destination for the extracted data. 261The 262.Fa offset 263argument 264specifies from where in the data portion of the option the value should be 265extracted; the first byte after the option type and length is 266accessed by specifying an offset of zero. 267.Pp 268It is expected that each field is aligned on its natural boundaries 269as described in Appendix B of RFC2460, but the function must not 270rely on the alignment. 271.Pp 272The function returns the offset for the next field 273(i.e., 274.Fa offset 275+ 276.Fa vallen ) 277which can be used when extracting option content with 278multiple fields. 279Robust receivers might want to verify alignment before calling 280this function. 281.\" 282.Sh DIAGNOSTICS 283All the functions return 284\-1 285on an error. 286.\" 287.Sh EXAMPLES 288draft-ietf-ipngwg-rfc2292bis-08.txt 289gives comprehensive examples in Section 23. 290.Pp 291KAME also provides examples in the advapitest directory of its kit. 292.\" 293.Sh SEE ALSO 294.Rs 295.%A W. Stevens 296.%A M. Thomas 297.%A E. Nordmark 298.%A T. Jinmei 299.%T "Advanced Sockets API for IPv6" 300.%N draft-ietf-ipngwg-rfc2292bis-08 301.%D October 2002 302.Re 303.Rs 304.%A S. Deering 305.%A R. Hinden 306.%T "Internet Protocol, Version 6 (IPv6) Specification" 307.%N RFC2460 308.%D December 1998 309.Re 310.Sh HISTORY 311The implementation first appeared in KAME advanced networking kit. 312.Sh STANDARDS 313The functions 314are documented in 315.Dq Advanced Sockets API for IPv6 316.Pq draft-ietf-ipngwg-rfc2292bis-08.txt . 317.\" 318.Sh BUGS 319The text was shamelessly copied from internet-drafts for RFC2292bis. 320