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