1 .\" Copyright (c) 1983, 1987, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University 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 REGENTS 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 REGENTS 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
32 .\" $Id: inet6_option_space.3,v 1.4 2000/02/05 10:32:24 jinmei Exp $
33 .\" $FreeBSD: src/lib/libc/net/inet6_option_space.3,v 1.1.2.7 2002/12/29 16:35:34 schweikh Exp $
34 .\" $DragonFly: src/lib/libcr/net/Attic/inet6_option_space.3,v 1.2 2003/06/17 04:26:44 dillon Exp $
37 .Dt INET6_OPTION_SPACE 3
41 .Nm inet6_option_space ,
42 .Nm inet6_option_init ,
43 .Nm inet6_option_append ,
44 .Nm inet6_option_alloc ,
45 .Nm inet6_option_next ,
47 .Nd IPv6 Hop-by-Hop and Destination Options manipulation
55 .Fn inet6_option_space "int nbytes"
57 .Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
59 .Fn inet6_option_append "struct cmsghdr *cmsg" "const u_int8_t *typep" "int multx" "int plusy"
61 .Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy"
63 .Fn inet6_option_next "const struct cmsghdr *cmsg" "u_int8_t **tptrp"
65 .Fn inet6_option_find "const struct cmsghdr *cmsg" "u_int8_t **tptrp" "int type"
69 Building and parsing the Hop-by-Hop and Destination options is
70 complicated due to alignment constraints, padding and
71 ancillary data manipulation.
72 RFC2292 defines a set of functions to help the application.
73 The function prototypes for
74 these functions are all in the
78 .Ss inet6_option_space
79 .Fn inet6_option_space
80 returns the number of bytes required to hold an option when it is stored as
81 ancillary data, including the
83 structure at the beginning,
84 and any padding at the end
85 (to make its size a multiple of 8 bytes).
86 The argument is the size of the structure defining the option,
87 which must include any pad bytes at the beginning
92 the type byte, the length byte, and the option data.
94 Note: If multiple options are stored in a single ancillary data
95 object, which is the recommended technique, this function
96 overestimates the amount of space required by the size of
102 is the number of options to be stored in the object.
103 This is of little consequence, since it is assumed that most
104 Hop-by-Hop option headers and Destination option headers carry only
106 (appendix B of [RFC-2460]).
108 .Ss inet6_option_init
109 .Fn inet6_option_init
110 is called once per ancillary data object that will
111 contain either Hop-by-Hop or Destination options.
119 is a pointer to previously allocated space that will contain the
120 ancillary data object.
121 It must be large enough to contain all the
122 individual options to be added by later calls to
123 .Fn inet6_option_append
125 .Fn inet6_option_alloc .
128 is a pointer to a pointer to a
132 is initialized by this function to point to the
134 structure constructed by this function in the buffer pointed to by
148 structure pointed to by
151 .Ss inet6_option_append
152 This function appends a Hop-by-Hop option or a Destination option
153 into an ancillary data object that has been initialized by
154 .Fn inet6_option_init .
155 This function returns
164 structure that must have been
166 .Fn inet6_option_init .
169 is a pointer to the 8-bit option type.
170 It is assumed that this
171 field is immediately followed by the 8-bit option data length field,
172 which is then followed immediately by the option data.
174 initializes these three fields
175 (the type-length-value, or TLV)
176 before calling this function.
178 The option type must have a value from
190 options, respectively.)
192 The option data length must have a value between
196 inclusive, and is the length of the option data that follows.
201 in the alignment term
203 It must have a value of
213 in the alignment term
215 It must have a value between
221 .Ss inet6_option_alloc
222 This function appends a Hop-by-Hop option or a Destination option
223 into an ancillary data object that has been initialized by
224 .Fn inet6_option_init .
225 This function returns a pointer to the 8-bit
226 option type field that starts the option on success, or
230 The difference between this function and
231 .Fn inet6_option_append
232 is that the latter copies the contents of a previously built option into
233 the ancillary data object while the current function returns a
234 pointer to the space in the data object where the option's TLV must
235 then be built by the caller.
240 structure that must have been
242 .Fn inet6_option_init .
245 is the value of the option data length byte for this option.
246 This value is required as an argument to allow the function to
247 determine if padding must be appended at the end of the option.
249 .Fn inet6_option_append
250 function does not need a data length argument
251 since the option data length must already be stored by the caller.)
256 in the alignment term
258 It must have a value of
268 in the alignment term
270 It must have a value between
276 .Ss inet6_option_next
277 This function processes the next Hop-by-Hop option or Destination
278 option in an ancillary data object.
279 If another option remains to be
280 processed, the return value of the function is
285 the 8-bit option type field
286 (which is followed by the 8-bit option
287 data length, followed by the option data).
288 If no more options remain
289 to be processed, the return value is
295 If an error occurs, the return value is
317 is a pointer to a pointer to an 8-bit byte and
320 by the function to remember its place in the ancillary data object
321 each time the function is called.
322 The first time this function is
323 called for a given ancillary data object,
328 Each time this function returns success,
331 option type field for the next option to be processed.
333 .Ss inet6_option_find
334 This function is similar to the previously described
335 .Fn inet6_option_next
336 function, except this function lets the caller
337 specify the option type to be searched for, instead of always
338 returning the next option in the ancillary data object.
355 is a pointer to a pointer to an 8-bit byte and
358 by the function to remember its place in the ancillary data object
359 each time the function is called.
360 The first time this function is
361 called for a given ancillary data object,
366 This function starts searching for an option of the specified type
367 beginning after the value of
369 If an option of the specified
370 type is located, this function returns
375 bit option type field for the option of the specified type.
377 option of the specified type is not located, the return value is
383 If an error occurs, the return value is
391 .Fn inet6_option_init
393 .Fn inet6_option_append
400 .Fn inet6_option_alloc
406 .Fn inet6_option_next
408 .Fn inet6_option_find
418 RFC2292 gives comprehensive examples in chapter 6.
424 .%T "Advanced Sockets API for IPv6"
431 .%T "Internet Protocol, Version 6 (IPv6) Specification"
437 The implementation first appeared in KAME advanced networking kit.
442 .Dq Advanced Sockets API for IPv6
446 The text was shamelessly copied from RFC2292.