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.8 2008/04/20 22:24:53 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
165 when an error occurs.
169 argument is a pointer to the
171 structure that was initialized by a call to
172 .Fn inet6_option_init .
176 argument is a pointer to the 8-bit option type.
178 encoded as type-length-value tuples and it is assumed that
181 field is immediately followed by the 8-bit option data length field,
182 which is then followed by the option data.
187 .Li 1 are reserved for the
191 options respectively.
192 All other values from
196 are available for applications to use.
198 The option data length, since it is stored in 8 bites, must have a
210 in the alignment term
212 and indicates the byte alignment necessary for the data.
213 Alignments may be specified as
219 bytes, which is no alignment, 16 bit, 32 bit and 64 bit alignments
227 in the alignment term
229 and must have a value between
233 inclusive, indicating the amount of padding that is necessary for an
236 .Ss inet6_option_alloc
238 .Fn inet6_option_alloc
239 function appends a Hop-by-Hop option or a Destination option into an
240 ancillary data object that has previously been initialized by a call to
241 .Fn inet6_option_init .
243 .Fn inet6_option_alloc
244 function returns a pointer to the 8-bit option type field that at the
245 beginning of the allocated the option on success, or
249 The difference between the
250 .Fn inet6_option_alloc
252 .Fn inet6_option_append
253 functions is that the latter copies the contents of a previously built
254 option into the ancillary data object while the former returns a
255 pointer to the place in the data object where the option's TLV must
256 then be built by the application.
260 argument is a pointer to a
262 structure that was initialized by
263 .Fn inet6_option_init .
267 argument is the value of the option data length byte for this option.
268 This value is required as an argument to allow the function to
269 determine if padding must be appended at the end of the option.
271 .Fn inet6_option_append
272 function does not need a data length argument
273 since the option data length must already be stored by the caller)
280 are identical to the arguments of the same name described in the
281 .Fn inet6_option_init
284 .Ss inet6_option_next
286 .Fn inet6_option_next
287 function is used to process Hop-by-Hop and Destination options that
288 are present in an ancillary data object.
289 When an option remains to
290 be processed, the return value of the
291 .Fn inet6_option_next
296 argument points to the 8-bit option type field, which is followed by
297 the 8-bit option data length, and then the option data.
299 options remain to be processed, the return value is
305 and when an error occurs, the return value is
311 This set of return values allows a program to easily loop through all
312 the options in an ancillary data object, checking for the error and
313 end of stream conditions along the way.
315 When a valid option is returned the
332 argument is a pointer to a pointer to an 8-bit byte and
334 is used by the function to remember its place in the ancillary data
335 object each time the function is called.
337 .Fn inet6_option_next
338 function is called for the first time on a given ancillary data object,
343 Each time the function returns success,
346 argument points to the 8-bit option type field for the next option to
349 .Ss inet6_option_find
351 .Fn inet6_option_find
352 function allows an application to search for a particular option type
353 in an ancillary data object.
356 argument is a pointer to
358 structure in which the
371 argument is handled exactly as in the
372 .Fn inet6_option_next
373 function described above.
376 .Fn inet6_option_find
377 function starts searching for an option of the specified type
378 beginning after the value of
382 RFC 2292 gives comprehensive examples in chapter 6.
386 .Fn inet6_option_init
388 .Fn inet6_option_append
396 .Fn inet6_option_alloc
402 .Fn inet6_option_next
404 .Fn inet6_option_find
405 detect an error they return
417 .%T "Advanced Sockets API for IPv6"
424 .%T "Internet Protocol, Version 6 (IPv6) Specification"
430 The functions are documented in
431 .Dq Advanced Sockets API for IPv6
435 The implementation first appeared in KAME advanced networking kit.