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