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