lib/libc/net/inet6_opt_init.3

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