1 .\" $KAME: inet6_option_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $
2 .\" $FreeBSD: src/lib/libc/net/inet6_option_space.3,v 1.16 2005/01/23 16:02:48 gnn Exp $
3 .\" $DragonFly: src/lib/libc/net/inet6_option_space.3,v 1.7 2007/11/23 23:16:36 swildner Exp $
5 .\" Copyright (C) 2004 WIDE Project.
6 .\" All rights reserved.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the project nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Dt INET6_OPTION_SPACE 3
37 .Nm inet6_option_space ,
38 .Nm inet6_option_init ,
39 .Nm inet6_option_append ,
40 .Nm inet6_option_alloc ,
41 .Nm inet6_option_next ,
43 .Nd IPv6 Hop-by-Hop and Destination Option Manipulation
51 .Fn inet6_option_space "int nbytes"
53 .Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
55 .Fn inet6_option_append "struct cmsghdr *cmsg" "const u_int8_t *typep" "int multx" "int plusy"
57 .Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy"
59 .Fn inet6_option_next "const struct cmsghdr *cmsg" "u_int8_t **tptrp"
61 .Fn inet6_option_find "const struct cmsghdr *cmsg" "u_int8_t **tptrp" "int type"
65 Manipulating and parsing IPv6's Hop-by-Hop and Destination options is
66 complicated by the need to properly align and pad data as well as the
67 need to manipulate ancillary information that is not part of the data
69 RFC 2292 defines a set of functions, which are implemented as
70 part of the Kame libraries, to support help developers create, change,
71 and parse Hop-by-Hope and Destination options.
73 for the option functions are defined in the
77 .Ss inet6_option_space
78 In order to determine the amount of space necessary to hold any option
80 .Fn inet6_option_space
82 It returns the number of bytes required to hold
83 an option when it is stored as ancillary data, including the
85 structure at the beginning, and any necessary padding at the end.
88 argument indicates the size of the structure defining the option,
89 and must include any pad bytes at the beginning (the value
93 the type byte, the length byte, and the option data.
95 Note: If multiple options are stored in a single ancillary data
96 object, which is the recommended technique, the
97 .Fn inet6_option_space
98 function overestimates the amount of space required by the size of
103 is the number of options to be stored in the object.
105 no impact because it is assumed that most Hop-by-Hop and Destination
106 option headers carry only one option as indicated in appendix B of RFC 2460.
108 .Ss inet6_option_init
110 .Fn inet6_option_init
111 function is called to initialize any ancillary data object that will contain
112 a Hop-by-Hop or Destination option.
117 when an error occurs.
121 argument points to a previously allocated area of memory which must be
122 large enough to contain all the arguments that the application indents
124 .Fn inet6_option_append
126 .Fn inet6_option_alloc
131 argument is a pointer to a pointer to a
139 structure which is constructed by this function and stored in the
140 area of memory pointed to by
153 structure mentioned above.
155 .Ss inet6_option_append
156 This function appends a Hop-by-Hop option or a Destination option into
157 an ancillary data object previously initialized by a call to
158 .Fn inet6_option_init .
160 .Fn inet6_option_append function returns
164 when an error occurs.
168 argument is a pointer to the
170 structure that was initialized by a call to
171 .Fn inet6_option_init .
175 argument is a pointer to the 8-bit option type.
177 encoded as type-length-value tuples and it is assumed that
180 field is immediately followed by the 8-bit option data length field,
181 which is then followed by the option data.
186 .Li 1 are reserved for the
190 options respectively.
191 All other values from
195 are available for applications to use.
197 The option data length, since it is stored in 8 bites, must have a
209 in the alignment term
211 and indicates the byte alignment necessary for the data.
212 Alignments may be specified as
218 bytes, which is no alignment, 16 bit, 32 bit and 64 bit alignments
226 in the alignment term
228 and must have a value between
232 inclusive, indicating the amount of padding that is necessary for an
235 .Ss inet6_option_alloc
237 .Fn inet6_option_alloc
238 function appends a Hop-by-Hop option or a Destination option into an
239 ancillary data object that has previously been initialized by a call to
240 .Fn inet6_option_init .
242 .Fn inet6_option_alloc
243 function returns a pointer to the 8-bit option type field that at the
244 beginning of the allocated the option on success, or
248 The difference between the
249 .Fn inet6_option_alloc
251 .Fn inet6_option_append
252 functions is that the latter copies the contents of a previously built
253 option into the ancillary data object while the former returns a
254 pointer to the place in the data object where the option's TLV must
255 then be built by the application.
259 argument is a pointer to a
261 structure that was initialized by
262 .Fn inet6_option_init .
266 argument is the value of the option data length byte for this option.
267 This value is required as an argument to allow the function to
268 determine if padding must be appended at the end of the option.
270 .Fn inet6_option_append
271 function does not need a data length argument
272 since the option data length must already be stored by the caller)
279 are identical to the arguments of the same name described in the
280 .Fn inet6_option_init
283 .Ss inet6_option_next
285 .Fn inet6_option_next
286 function is used to process Hop-by-Hop and Destination options that
287 are present in an ancillary data object.
288 When an option remains to
289 be processed, the return value of the
290 .Fn inet6_option_next
295 argument points to the 8-bit option type field, which is followed by
296 the 8-bit option data length, and then the option data.
298 options remain to be processed, the return value is
304 and when an error occurs, the return value is
310 This set of return values allows a program to easily loop through all
311 the options in an ancillary data object, checking for the error and
312 end of stream conditions along the way.
314 When a valid option is returned the
331 argument is a pointer to a pointer to an 8-bit byte and
333 is used by the function to remember its place in the ancillary data
334 object each time the function is called.
336 .Fn inet6_option_next
337 function is called for the first time on a given ancillary data object,
342 Each time the function returns success,
345 argument points to the 8-bit option type field for the next option to
348 .Ss inet6_option_find
350 .Fn inet6_option_find
351 function allows an application to search for a particular option type
352 in an ancillary data object.
355 argument is a pointer to
357 structure in which the
370 argument is handled exactly as in the
371 .Fn inet6_option_next
372 function described above.
375 .Fn inet6_option_find
376 function starts searching for an option of the specified type
377 beginning after the value of
381 RFC 2292 gives comprehensive examples in chapter 6.
385 .Fn inet6_option_init
387 .Fn inet6_option_append
395 .Fn inet6_option_alloc
401 .Fn inet6_option_next
403 .Fn inet6_option_find
404 detect an error they return
416 .%T "Advanced Sockets API for IPv6"
423 .%T "Internet Protocol, Version 6 (IPv6) Specification"
429 The functions are documented in
430 .Dq Advanced Sockets API for IPv6
434 The implementation first appeared in KAME advanced networking kit.