xref: /freebsd/lib/libc/net/inet6_option_space.3 (revision 2efeeba554cbd7bdee9cfe17641c8bd335c7972f)
1.\" Copyright (c) 1983, 1987, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
19.\"
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
30.\" SUCH DAMAGE.
31.\"
32.\"     $Id: inet6_option_space.3,v 1.4 2000/02/05 10:32:24 jinmei Exp $
33.\" $FreeBSD$
34.\"
35.Dd December 10, 1999
36.Dt INET6_OPTION_SPACE 3
37.Os
38.\"
39.Sh NAME
40.Nm inet6_option_space ,
41.Nm inet6_option_init ,
42.Nm inet6_option_append ,
43.Nm inet6_option_alloc ,
44.Nm inet6_option_next ,
45.Nm inet6_option_find
46.Nd IPv6 Hop-by-Hop and Destination Options manipulation
47.\"
48.Sh LIBRARY
49.Lb libc
50.Sh SYNOPSIS
51.In sys/types.h
52.In netinet/in.h
53.Ft "int"
54.Fn inet6_option_space "int nbytes"
55.Ft "int"
56.Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
57.Ft "int"
58.Fn inet6_option_append "struct cmsghdr *cmsg" "const u_int8_t *typep" "int multx" "int plusy"
59.Ft "u_int8_t *"
60.Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy"
61.Ft "int"
62.Fn inet6_option_next "const struct cmsghdr *cmsg" "u_int8_t **tptrp"
63.Ft "int"
64.Fn inet6_option_find "const struct cmsghdr *cmsg" "u_int8_t **tptrp" "int type"
65.\"
66.Sh DESCRIPTION
67.\"
68Building and parsing the Hop-by-Hop and Destination options is
69complicated due to alignment constranints, padding and
70ancillary data manipulation.
71RFC2292 defines a set of functions to help the application.
72The function prototypes for
73these functions are all in the
74.Aq Li netinet/in.h
75header.
76.\"
77.Ss inet6_option_space
78The
79.Fn inet6_option_space
80function
81returns the number of bytes required to hold an option when it is stored as
82ancillary data, including the
83.Li cmsghdr
84structure at the beginning,
85and any padding at the end
86(to make its size a multiple of 8 bytes).
87The argument is the size of the structure defining the option,
88which must include any pad bytes at the beginning
89(the value
90.Li y
91in the alignment term
92.Dq Li "xn + y" ) ,
93the type byte, the length byte, and the option data.
94.Pp
95Note: If multiple options are stored in a single ancillary data
96object, which is the recommended technique, this function
97overestimates the amount of space required by the size of
98.Li N-1
99.Li cmsghdr
100structures,
101where
102.Li N
103is the number of options to be stored in the object.
104This is of little consequence, since it is assumed that most
105Hop-by-Hop option headers and Destination option headers carry only
106one option
107(appendix B of [RFC-2460]).
108.\"
109.Ss inet6_option_init
110The
111.Fn inet6_option_init
112function
113is called once per ancillary data object that will
114contain either Hop-by-Hop or Destination options.
115It returns
116.Li 0
117on success or
118.Li -1
119on an error.
120.Pp
121The
122.Fa bp
123argument
124is a pointer to previously allocated space that will contain the
125ancillary data object.
126It must be large enough to contain all the
127individual options to be added by later calls to
128.Fn inet6_option_append
129and
130.Fn inet6_option_alloc .
131.Pp
132The
133.Fa cmsgp
134argument
135is a pointer to a pointer to a
136.Li cmsghdr
137structure.
138The
139.Fa *cmsgp
140argument
141is initialized by this function to point to the
142.Li cmsghdr
143structure constructed by this function in the buffer pointed to by
144.Fa bp .
145.Pp
146The
147.Fa type
148argument
149is either
150.Dv IPV6_HOPOPTS
151or
152.Dv IPV6_DSTOPTS .
153This
154.Fa type
155is stored in the
156.Li cmsg_type
157member of the
158.Li cmsghdr
159structure pointed to by
160.Fa *cmsgp .
161.\"
162.Ss inet6_option_append
163This function appends a Hop-by-Hop option or a Destination option
164into an ancillary data object that has been initialized by
165.Fn inet6_option_init .
166This function returns
167.Li 0
168if it succeeds or
169.Li -1
170on an error.
171.Pp
172The
173.Fa cmsg
174argument
175is a pointer to the
176.Li cmsghdr
177structure that must have been
178initialized by
179.Fn inet6_option_init .
180.Pp
181The
182.Fa typep
183argument
184is a pointer to the 8-bit option type.
185It is assumed that this
186field is immediately followed by the 8-bit option data length field,
187which is then followed immediately by the option data.
188The caller
189initializes these three fields
190(the type-length-value, or TLV)
191before calling this function.
192.Pp
193The option type must have a value from
194.Li 2
195to
196.Li 255 ,
197inclusive.
198.Li ( 0
199and
200.Li 1
201are reserved for the
202.Li Pad1
203and
204.Li PadN
205options, respectively.)
206.Pp
207The option data length must have a value between
208.Li 0
209and
210.Li 255 ,
211inclusive, and is the length of the option data that follows.
212.Pp
213The
214.Fa multx
215argument
216is the value
217.Li x
218in the alignment term
219.Dq Li xn + y .
220It must have a value of
221.Li 1 ,
222.Li 2 ,
223.Li 4 ,
224or
225.Li 8 .
226.Pp
227The
228.Fa plusy
229argument
230is the value
231.Li y
232in the alignment term
233.Dq Li xn + y .
234It must have a value between
235.Li 0
236and
237.Li 7 ,
238inclusive.
239.\"
240.Ss inet6_option_alloc
241This function appends a Hop-by-Hop option or a Destination option
242into an ancillary data object that has been initialized by
243.Fn inet6_option_init .
244This function returns a pointer to the 8-bit
245option type field that starts the option on success, or
246.Dv NULL
247on an error.
248.Pp
249The difference between this function and
250.Fn inet6_option_append
251is that the latter copies the contents of a previously built option into
252the ancillary data object while the current function returns a
253pointer to the space in the data object where the option's TLV must
254then be built by the caller.
255.Pp
256The
257.Fa cmsg
258argument
259is a pointer to the
260.Li cmsghdr
261structure that must have been
262initialized by
263.Fn inet6_option_init .
264.Pp
265The
266.Fa datalen
267argument
268is the value of the option data length byte for this option.
269This value is required as an argument to allow the function to
270determine if padding must be appended at the end of the option.
271(The
272.Fn inet6_option_append
273function does not need a data length argument
274since the option data length must already be stored by the caller.)
275.Pp
276The
277.Fa multx
278argument
279is the value
280.Li x
281in the alignment term
282.Dq Li xn + y .
283It must have a value of
284.Li 1 ,
285.Li 2 ,
286.Li 4 ,
287or
288.Li 8 .
289.Pp
290The
291.Fa plusy
292argument
293is the value
294.Li y
295in the alignment term
296.Dq Li xn + y .
297It must have a value between
298.Li 0
299and
300.Li 7 ,
301inclusive.
302.\"
303.Ss inet6_option_next
304This function processes the next Hop-by-Hop option or Destination
305option in an ancillary data object.
306If another option remains to be
307processed, the return value of the function is
308.Li 0
309and
310.Fa *tptrp
311points to
312the 8-bit option type field
313(which is followed by the 8-bit option
314data length, followed by the option data).
315If no more options remain
316to be processed, the return value is
317.Li -1
318and
319.Fa *tptrp
320is
321.Dv NULL .
322If an error occurs, the return value is
323.Li -1
324and
325.Fa *tptrp
326is not
327.Dv NULL .
328.Pp
329The
330.Fa cmsg
331argument
332is a pointer to
333.Li cmsghdr
334structure of which
335.Li cmsg_level
336equals
337.Dv IPPROTO_IPV6
338and
339.Li cmsg_type
340equals either
341.Dv IPV6_HOPOPTS
342or
343.Dv IPV6_DSTOPTS .
344.Pp
345The
346.Fa tptrp
347argument
348is a pointer to a pointer to an 8-bit byte and
349.Fa *tptrp
350is used
351by the function to remember its place in the ancillary data object
352each time the function is called.
353The first time this function is
354called for a given ancillary data object,
355.Fa *tptrp
356must be set to
357.Dv NULL .
358.Pp
359Each time this function returns success,
360.Fa *tptrp
361points to the 8-bit
362option type field for the next option to be processed.
363.\"
364.Ss inet6_option_find
365This function is similar to the previously described
366.Fn inet6_option_next
367function, except this function lets the caller
368specify the option type to be searched for, instead of always
369returning the next option in the ancillary data object.
370The
371.Fa cmsg
372argument
373is a
374pointer to
375.Li cmsghdr
376structure of which
377.Li cmsg_level
378equals
379.Dv IPPROTO_IPV6
380and
381.Li cmsg_type
382equals either
383.Dv IPV6_HOPOPTS
384or
385.Dv IPV6_DSTOPTS .
386.Pp
387The
388.Fa tptrp
389argument
390is a pointer to a pointer to an 8-bit byte and
391.Fa *tptrp
392is used
393by the function to remember its place in the ancillary data object
394each time the function is called.
395The first time this function is
396called for a given ancillary data object,
397.Fa *tptrp
398must be set to
399.Dv NULL .
400.Pa
401This function starts searching for an option of the specified type
402beginning after the value of
403.Fa *tptrp .
404If an option of the specified
405type is located, this function returns
406.Li 0
407and
408.Fa *tptrp
409points to the 8-
410bit option type field for the option of the specified type.
411If an
412option of the specified type is not located, the return value is
413.Li -1
414and
415.Fa *tptrp
416is
417.Dv NULL .
418If an error occurs, the return value is
419.Li -1
420and
421.Fa *tptrp
422is not
423.Dv NULL .
424.\"
425.Sh DIAGNOSTICS
426The
427.Fn inet6_option_init
428and
429.Fn inet6_option_append
430functions
431return
432.Li 0
433on success or
434.Li -1
435on an error.
436.Pp
437The
438.Fn inet6_option_alloc
439function
440returns
441.Dv NULL
442on an error.
443.Pp
444On errors,
445.Fn inet6_option_next
446and
447.Fn inet6_option_find
448return
449.Li -1
450setting
451.Fa *tptrp
452to non
453.Dv NULL
454value.
455.\"
456.Sh EXAMPLES
457RFC2292 gives comprehensive examples in chapter 6.
458.\"
459.Sh SEE ALSO
460.Rs
461.%A W. Stevens
462.%A M. Thomas
463.%T "Advanced Sockets API for IPv6"
464.%N RFC2292
465.%D February 1998
466.Re
467.Rs
468.%A S. Deering
469.%A R. Hinden
470.%T "Internet Protocol, Version 6 (IPv6) Specification"
471.%N RFC2460
472.%D December 1998
473.Re
474.\"
475.Sh HISTORY
476The implementation first appeared in KAME advanced networking kit.
477.\"
478.Sh STANDARDS
479The functions
480are documented in
481.Dq Advanced Sockets API for IPv6
482(RFC2292).
483.\"
484.Sh BUGS
485The text was shamelessly copied from RFC2292.
486