| blob | c6407ae3f779e2355500258c5d36bba587a91c48 |
1 .\" $NetBSD: inet6_option_space.3,v 1.3 2010/03/22 19:30:54 joerg Exp $
2 .\" $KAME: inet6_option_space.3,v 1.7 2000/05/17 14:32:13 itojun Exp $
3 .\"
4 .\" Copyright (c) 1983, 1987, 1991, 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" SUCH DAMAGE.
30 .\"
31 .Dd December 10, 1999
32 .Dt INET6_OPTION_SPACE 3
33 .Os
34 .\"
35 .Sh NAME
36 .Nm inet6_option_space ,
37 .Nm inet6_option_init ,
38 .Nm inet6_option_append ,
39 .Nm inet6_option_alloc ,
40 .Nm inet6_option_next ,
41 .Nm inet6_option_find
42 .Nd IPv6 Hop-by-Hop and Destination Options manipulation
43 .\"
44 .Sh SYNOPSIS
45 .In netinet/in.h
46 .Ft "int"
47 .Fn inet6_option_space "int nbytes"
48 .Ft "int"
49 .Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
50 .Ft "int"
51 .Fn inet6_option_append "struct cmsghdr *cmsg" "const uint8_t *typep" "int multx" "int plusy"
52 .Ft "uint8_t *"
53 .Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy"
54 .Ft "int"
55 .Fn inet6_option_next "const struct cmsghdr *cmsg" "uint8_t **tptrp"
56 .Ft "int"
57 .Fn inet6_option_find "const struct cmsghdr *cmsg" "uint8_t **tptrp" "int type"
58 .\"
59 .Sh DESCRIPTION
60 .\"
61 Building and parsing the Hop-by-Hop and Destination options is
62 complicated due to alignment constraints, padding and
63 ancillary data manipulation.
64 RFC 2292 defines a set of functions to help the application.
65 The function prototypes for
66 these functions are all in the
67 .In netinet/in.h
68 header.
69 .\"
70 .Ss inet6_option_space
71 .Fn inet6_option_space
72 returns the number of bytes required to hold an option when it is stored as
73 ancillary data, including the
74 .Li cmsghdr
75 structure at the beginning,
76 and any padding at the end
77 .Po
78 to make its size a multiple of 8 bytes
79 .Pc .
80 The argument is the size of the structure defining the option,
81 which must include any pad bytes at the beginning
82 .Po
83 the value
84 .Li y
85 in the alignment term
86 .Dq Li xn + y
87 .Pc ,
88 the type byte, the length byte, and the option data.
89 .Pp
90 Note: If multiple options are stored in a single ancillary data
91 object, which is the recommended technique, this function
92 overestimates the amount of space required by the size of
93 .Li N-1
94 .Li cmsghdr
95 structures,
96 where
97 .Li N
98 is the number of options to be stored in the object.
99 This is of little consequence, since it is assumed that most
100 Hop-by-Hop option headers and Destination option headers carry only
101 one option
102 .Pq appendix B of [RFC 2460] .
103 .\"
104 .Ss inet6_option_init
105 .Fn inet6_option_init
106 is called once per ancillary data object that will
107 contain either Hop-by-Hop or Destination options.
108 It returns
109 .Li 0
110 on success or
111 .Li -1
112 on an error.
113 .Pp
114 .Fa bp
115 is a pointer to previously allocated space that will contain the
116 ancillary data object.
117 It must be large enough to contain all the
118 individual options to be added by later calls to
119 .Fn inet6_option_append
120 and
121 .Fn inet6_option_alloc .
122 .Pp
123 .Fa cmsgp
124 is a pointer to a pointer to a
125 .Li cmsghdr
126 structure.
127 .Fa *cmsgp
128 is initialized by this function to point to the
129 .Li cmsghdr
130 structure constructed by this function in the buffer pointed to by
131 .Fa bp .
132 .Pp
133 .Fa type
134 is either
135 .Dv IPV6_HOPOPTS
136 or
137 .Dv IPV6_DSTOPTS .
138 This
139 .Fa type
140 is stored in the
141 .Li cmsg_type
142 member of the
143 .Li cmsghdr
144 structure pointed to by
145 .Fa *cmsgp .
146 .\"
147 .Ss inet6_option_append
148 This function appends a Hop-by-Hop option or a Destination option
149 into an ancillary data object that has been initialized by
150 .Fn inet6_option_init .
151 This function returns
152 .Li 0
153 if it succeeds or
154 .Li -1
155 on an error.
156 .Pp
157 .Fa cmsg
158 is a pointer to the
159 .Li cmsghdr
160 structure that must have been
161 initialized by
162 .Fn inet6_option_init .
163 .Pp
164 .Fa typep
165 is a pointer to the 8-bit option type.
166 It is assumed that this
167 field is immediately followed by the 8-bit option data length field,
168 which is then followed immediately by the option data.
169 The caller
170 initializes these three fields
171 .Pq the type-length-value, or TLV
172 before calling this function.
173 .Pp
174 The option type must have a value from
175 .Li 2
176 to
177 .Li 255 ,
178 inclusive.
179 .Po
180 .Li 0
181 and
182 .Li 1
183 are reserved for the
184 .Li Pad1
185 and
186 .Li PadN
187 options, respectively.
188 .Pc
189 .Pp
190 The option data length must have a value between
191 .Li 0
192 and
193 .Li 255 ,
194 inclusive, and is the length of the option data that follows.
195 .Pp
196 .Fa multx
197 is the value
198 .Li x
199 in the alignment term
200 .Dq Li xn + y .
201 It must have a value of
202 .Li 1 ,
203 .Li 2 ,
204 .Li 4 ,
205 or
206 .Li 8 .
207 .Pp
208 .Fa plusy
209 is the value
210 .Li y
211 in the alignment term
212 .Dq Li xn + y .
213 It must have a value between
214 .Li 0
215 and
216 .Li 7 ,
217 inclusive.
218 .\"
219 .Ss inet6_option_alloc
220 This function appends a Hop-by-Hop option or a Destination option
221 into an ancillary data object that has been initialized by
222 .Fn inet6_option_init .
223 This function returns a pointer to the 8-bit
224 option type field that starts the option on success, or
225 .Dv NULL
226 on an error.
227 .Pp
228 The difference between this function and
229 .Fn inet6_option_append
230 is that the latter copies the contents of a previously built option into
231 the ancillary data object while the current function returns a
232 pointer to the space in the data object where the option's TLV must
233 then be built by the caller.
234 .Pp
235 .Fa cmsg
236 is a pointer to the
237 .Li cmsghdr
238 structure that must have been
239 initialized by
240 .Fn inet6_option_init .
241 .Pp
242 .Fa datalen
243 is the value of the option data length byte for this option.
244 This value is required as an argument to allow the function to
245 determine if padding must be appended at the end of the option.
246 .Po
247 The
248 .Fn inet6_option_append
249 function does not need a data length argument
250 since the option data length must already be stored by the caller.
251 .Pc
252 .Pp
253 .Fa multx
254 is the value
255 .Li x
256 in the alignment term
257 .Dq Li xn + y .
258 It must have a value of
259 .Li 1 ,
260 .Li 2 ,
261 .Li 4 ,
262 or
263 .Li 8 .
264 .Pp
265 .Fa plusy
266 is the value
267 .Li y
268 in the alignment term
269 .Dq Li xn + y .
270 It must have a value between
271 .Li 0
272 and
273 .Li 7 ,
274 inclusive.
275 .\"
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
281 .Li 0
282 and
283 .Fa *tptrp
284 points to
285 the 8-bit option type field
286 .Po
287 which is followed by the 8-bit option
288 data length, followed by the option data
289 .Pc .
290 If no more options remain
291 to be processed, the return value is
292 .Li -1
293 and
294 .Fa *tptrp
295 is
296 .Dv NULL .
297 If an error occurs, the return value is
298 .Li -1
299 and
300 .Fa *tptrp
301 is not
302 .Dv NULL .
303 .Pp
304 .Fa cmsg
305 is a pointer to
306 .Li cmsghdr
307 structure of which
308 .Li cmsg_level
309 equals
310 .Dv IPPROTO_IPV6
311 and
312 .Li cmsg_type
313 equals either
314 .Dv IPV6_HOPOPTS
315 or
316 .Dv IPV6_DSTOPTS .
317 .Pp
318 .Fa tptrp
319 is a pointer to a pointer to an 8-bit byte and
320 .Fa *tptrp
321 is used
322 by the function to remember its place in the ancillary data object
323 each time the function is called.
324 The first time this function is
325 called for a given ancillary data object,
326 .Fa *tptrp
327 must be set to
328 .Dv NULL .
329 .Pp
330 Each time this function returns success,
331 .Fa *tptrp
332 points to the 8-bit
333 option type field for the next option to be processed.
334 .\"
335 .Ss inet6_option_find
336 This function is similar to the previously described
337 .Fn inet6_option_next
338 function, except this function lets the caller
339 specify the option type to be searched for, instead of always
340 returning the next option in the ancillary data object.
341 .Fa cmsg
342 is a
343 pointer to
344 .Li cmsghdr
345 structure of which
346 .Li cmsg_level
347 equals
348 .Dv IPPROTO_IPV6
349 and
350 .Li cmsg_type
351 equals either
352 .Dv IPV6_HOPOPTS
353 or
354 .Dv IPV6_DSTOPTS .
355 .Pp
356 .Fa tptrp
357 is a pointer to a pointer to an 8-bit byte and
358 .Fa *tptrp
359 is used
360 by the function to remember its place in the ancillary data object
361 each time the function is called.
362 The first time this function is
363 called for a given ancillary data object,
364 .Fa *tptrp
365 must be set to
366 .Dv NULL .
367 .Pa
368 This function starts searching for an option of the specified type
369 beginning after the value of
370 .Fa *tptrp .
371 If an option of the specified
372 type is located, this function returns
373 .Li 0
374 and
375 .Fa *tptrp
376 points to the 8-
377 bit option type field for the option of the specified type.
378 If an
379 option of the specified type is not located, the return value is
380 .Li -1
381 and
382 .Fa *tptrp
383 is
384 .Dv NULL .
385 If an error occurs, the return value is
386 .Li -1
387 and
388 .Fa *tptrp
389 is not
390 .Dv NULL .
391 .\"
392 .Sh EXAMPLES
393 RFC 2292 gives comprehensive examples in chapter 6.
394 .\"
395 .Sh DIAGNOSTICS
396 .Fn inet6_option_init
397 and
398 .Fn inet6_option_append
399 return
400 .Li 0
401 on success or
402 .Li -1
403 on an error.
404 .Pp
405 .Fn inet6_option_alloc
406 returns
407 .Dv NULL
408 on an error.
409 .Pp
410 On errors,
411 .Fn inet6_option_next
412 and
413 .Fn inet6_option_find
414 return
415 .Li -1
416 setting
417 .Fa *tptrp
418 to non
419 .Dv NULL
420 value.
421 .\"
422 .Sh SEE ALSO
423 .Rs
424 .%A W. Stevens
425 .%A M. Thomas
426 .%T "Advanced Sockets API for IPv6"
427 .%N RFC 2292
428 .%D February 1998
429 .Re
430 .Rs
431 .%A S. Deering
432 .%A R. Hinden
433 .%T "Internet Protocol, Version 6 (IPv6) Specification"
434 .%N RFC 2460
435 .%D December 1998
436 .Re
437 .\"
438 .Sh STANDARDS
439 The functions
440 are documented in
441 .Dq Advanced Sockets API for IPv6
442 .Pq RFC 2292 .
443 .\"
444 .Sh HISTORY
445 The implementation first appeared in KAME advanced networking kit.
446 .\"
447 .Sh BUGS
448 The text was shamelessly copied from RFC 2292.