Uniformly refer to RFCs as 'RFC xxxx' and not 'RFCxxxx' or 'RFC-xxxx'.
[dragonfly.git] / lib / libc / net / inet6_option_space.3
CommitLineData
f35d325e
HS
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 $
cabeba47 3.\" $DragonFly: src/lib/libc/net/inet6_option_space.3,v 1.7 2007/11/23 23:16:36 swildner Exp $
f35d325e
HS
4.\"
5.\" Copyright (C) 2004 WIDE Project.
6.\" All rights reserved.
984263bc
MD
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
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.
f35d325e 16.\" 3. Neither the name of the project nor the names of its contributors
984263bc
MD
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
f35d325e 20.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
984263bc
MD
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
f35d325e 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
984263bc
MD
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.\"
f35d325e 32.Dd December 23, 2004
984263bc
MD
33.Dt INET6_OPTION_SPACE 3
34.Os
35.\"
36.Sh NAME
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 ,
42.Nm inet6_option_find
f35d325e 43.Nd IPv6 Hop-by-Hop and Destination Option Manipulation
984263bc
MD
44.\"
45.Sh LIBRARY
46.Lb libc
47.Sh SYNOPSIS
48.In sys/types.h
49.In netinet/in.h
50.Ft "int"
51.Fn inet6_option_space "int nbytes"
52.Ft "int"
53.Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
54.Ft "int"
55.Fn inet6_option_append "struct cmsghdr *cmsg" "const u_int8_t *typep" "int multx" "int plusy"
56.Ft "u_int8_t *"
57.Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy"
58.Ft "int"
59.Fn inet6_option_next "const struct cmsghdr *cmsg" "u_int8_t **tptrp"
60.Ft "int"
61.Fn inet6_option_find "const struct cmsghdr *cmsg" "u_int8_t **tptrp" "int type"
62.\"
63.Sh DESCRIPTION
64.\"
f35d325e
HS
65Manipulating and parsing IPv6's Hop-by-Hop and Destination options is
66complicated by the need to properly align and pad data as well as the
67need to manipulate ancillary information that is not part of the data
68stream.
cabeba47 69RFC 2292 defines a set of functions, which are implemented as
f35d325e
HS
70part of the Kame libraries, to support help developers create, change,
71and parse Hop-by-Hope and Destination options.
72All of the prototypes
73for the option functions are defined in the
74.In netinet/in.h
75header file.
984263bc
MD
76.\"
77.Ss inet6_option_space
f35d325e
HS
78In order to determine the amount of space necessary to hold any option
79the
984263bc 80.Fn inet6_option_space
f35d325e
HS
81function is called.
82It returns the number of bytes required to hold
83an option when it is stored as ancillary data, including the
984263bc 84.Li cmsghdr
f35d325e
HS
85structure at the beginning, and any necessary padding at the end.
86The
87.Li nbytes
88argument indicates the size of the structure defining the option,
89and must include any pad bytes at the beginning (the value
984263bc
MD
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
f35d325e
HS
96object, which is the recommended technique, the
97.Fn inet6_option_space
98function overestimates the amount of space required by the size of
984263bc
MD
99.Li N-1
100.Li cmsghdr
f35d325e 101structures, where
984263bc
MD
102.Li N
103is the number of options to be stored in the object.
f35d325e
HS
104Usually this has
105no impact because it is assumed that most Hop-by-Hop and Destination
cabeba47 106option headers carry only one option as indicated in appendix B of RFC 2460.
984263bc
MD
107.\"
108.Ss inet6_option_init
f35d325e 109The
984263bc 110.Fn inet6_option_init
f35d325e
HS
111function is called to initialize any ancillary data object that will contain
112a Hop-by-Hop or Destination option.
984263bc
MD
113It returns
114.Li 0
f35d325e 115on success and
984263bc 116.Li -1
f35d325e 117when an error occurs.
984263bc 118.Pp
f35d325e 119The
984263bc 120.Fa bp
f35d325e
HS
121argument points to a previously allocated area of memory which must be
122large enough to contain all the arguments that the application indents
123to add later via
984263bc
MD
124.Fn inet6_option_append
125and
f35d325e
HS
126.Fn inet6_option_alloc
127routines.
984263bc 128.Pp
f35d325e 129The
984263bc 130.Fa cmsgp
f35d325e 131argument is a pointer to a pointer to a
984263bc
MD
132.Li cmsghdr
133structure.
f35d325e 134The
984263bc 135.Fa *cmsgp
f35d325e
HS
136argument
137points to a
984263bc 138.Li cmsghdr
f35d325e
HS
139structure which is constructed by this function and stored in the
140area of memory pointed to by
984263bc
MD
141.Fa bp .
142.Pp
f35d325e 143The
984263bc
MD
144.Fa type
145is either
146.Dv IPV6_HOPOPTS
147or
f35d325e
HS
148.Dv IPV6_DSTOPTS
149and is stored in the
984263bc
MD
150.Li cmsg_type
151member of the
152.Li cmsghdr
f35d325e 153structure mentioned above.
984263bc
MD
154.\"
155.Ss inet6_option_append
f35d325e
HS
156This function appends a Hop-by-Hop option or a Destination option into
157an ancillary data object previously initialized by a call to
984263bc 158.Fn inet6_option_init .
f35d325e
HS
159The
160.Fn inet6_option_append function returns
984263bc
MD
161.Li 0
162if it succeeds or
163.Li -1
f35d325e 164when an error occurs.
984263bc 165.Pp
f35d325e 166The
984263bc 167.Fa cmsg
f35d325e 168argument is a pointer to the
984263bc 169.Li cmsghdr
f35d325e 170structure that was initialized by a call to
984263bc
MD
171.Fn inet6_option_init .
172.Pp
f35d325e
HS
173The
174.Fa typep
175argument is a pointer to the 8-bit option type.
176All options are
177encoded as type-length-value tuples and it is assumed that
178the
984263bc 179.Fa typep
984263bc 180field is immediately followed by the 8-bit option data length field,
f35d325e 181which is then followed by the option data.
984263bc 182.Pp
f35d325e
HS
183The option types of
184.Li 0
984263bc 185and
f35d325e 186.Li 1 are reserved for the
984263bc
MD
187.Li Pad1
188and
189.Li PadN
f35d325e
HS
190options respectively.
191All other values from
192.Li 2
193through
194.Li 255
195are available for applications to use.
984263bc 196.Pp
f35d325e
HS
197The option data length, since it is stored in 8 bites, must have a
198value between
984263bc
MD
199.Li 0
200and
201.Li 255 ,
f35d325e 202inclusive.
984263bc 203.Pp
f35d325e 204The
984263bc 205.Fa multx
f35d325e 206argument
984263bc
MD
207is the value
208.Li x
209in the alignment term
f35d325e
HS
210.Dq Li xn + y
211and indicates the byte alignment necessary for the data.
212Alignments may be specified as
984263bc
MD
213.Li 1 ,
214.Li 2 ,
215.Li 4 ,
216or
f35d325e
HS
217.Li 8
218bytes, which is no alignment, 16 bit, 32 bit and 64 bit alignments
219respectively.
984263bc 220.Pp
f35d325e 221The
984263bc 222.Fa plusy
f35d325e 223argument
984263bc
MD
224is the value
225.Li y
226in the alignment term
f35d325e
HS
227.Dq Li xn + y
228and must have a value between
984263bc
MD
229.Li 0
230and
231.Li 7 ,
f35d325e
HS
232inclusive, indicating the amount of padding that is necessary for an
233option.
984263bc
MD
234.\"
235.Ss inet6_option_alloc
f35d325e
HS
236The
237.Fn inet6_option_alloc
238function appends a Hop-by-Hop option or a Destination option into an
239ancillary data object that has previously been initialized by a call to
984263bc 240.Fn inet6_option_init .
f35d325e
HS
241The
242.Fn inet6_option_alloc
243function returns a pointer to the 8-bit option type field that at the
244beginning of the allocated the option on success, or
984263bc
MD
245.Dv NULL
246on an error.
247.Pp
f35d325e
HS
248The difference between the
249.Fn inet6_option_alloc
250and
984263bc 251.Fn inet6_option_append
f35d325e
HS
252functions is that the latter copies the contents of a previously built
253option into the ancillary data object while the former returns a
254pointer to the place in the data object where the option's TLV must
255then be built by the application.
984263bc 256.Pp
f35d325e 257The
984263bc 258.Fa cmsg
f35d325e 259argument is a pointer to a
984263bc 260.Li cmsghdr
f35d325e 261structure that was initialized by
984263bc
MD
262.Fn inet6_option_init .
263.Pp
f35d325e 264The
984263bc 265.Fa datalen
f35d325e 266argument is the value of the option data length byte for this option.
984263bc
MD
267This value is required as an argument to allow the function to
268determine if padding must be appended at the end of the option.
269(The
270.Fn inet6_option_append
271function does not need a data length argument
f35d325e 272since the option data length must already be stored by the caller)
984263bc 273.Pp
f35d325e 274The
984263bc 275.Fa multx
984263bc 276and
f35d325e
HS
277.Fa plusy
278arguments
279are identical to the arguments of the same name described in the
280.Fn inet6_option_init
281function above.
984263bc
MD
282.\"
283.Ss inet6_option_next
f35d325e
HS
284The
285.Fn inet6_option_next
286function is used to process Hop-by-Hop and Destination options that
287are present in an ancillary data object.
288When an option remains to
289be processed, the return value of the
290.Fn inet6_option_next
291function is
984263bc 292.Li 0
f35d325e 293and the
984263bc 294.Fa *tptrp
f35d325e
HS
295argument points to the 8-bit option type field, which is followed by
296the 8-bit option data length, and then the option data.
297When no more
298options remain to be processed, the return value is
984263bc
MD
299.Li -1
300and
301.Fa *tptrp
302is
f35d325e
HS
303.Dv NULL
304and when an error occurs, the return value is
984263bc 305.Li -1
f35d325e 306but the
984263bc 307.Fa *tptrp
f35d325e 308argument is not
984263bc 309.Dv NULL .
f35d325e
HS
310This set of return values allows a program to easily loop through all
311the options in an ancillary data object, checking for the error and
312end of stream conditions along the way.
984263bc 313.Pp
f35d325e 314When a valid option is returned the
984263bc 315.Fa cmsg
f35d325e 316argument points to a
984263bc 317.Li cmsghdr
f35d325e 318where the
984263bc
MD
319.Li cmsg_level
320equals
321.Dv IPPROTO_IPV6
322and
323.Li cmsg_type
f35d325e 324is either
984263bc
MD
325.Dv IPV6_HOPOPTS
326or
327.Dv IPV6_DSTOPTS .
328.Pp
f35d325e 329The
984263bc 330.Fa tptrp
f35d325e 331argument is a pointer to a pointer to an 8-bit byte and
984263bc 332.Fa *tptrp
f35d325e
HS
333is used by the function to remember its place in the ancillary data
334object each time the function is called.
335When the
336.Fn inet6_option_next
337function is called for the first time on a given ancillary data object,
984263bc
MD
338.Fa *tptrp
339must be set to
340.Dv NULL .
341.Pp
f35d325e
HS
342Each time the function returns success,
343the
984263bc 344.Fa *tptrp
f35d325e
HS
345argument points to the 8-bit option type field for the next option to
346be processed.
984263bc
MD
347.\"
348.Ss inet6_option_find
f35d325e
HS
349The
350.Fn inet6_option_find
351function allows an application to search for a particular option type
352in an ancillary data object.
353The
984263bc 354.Fa cmsg
f35d325e 355argument is a pointer to
984263bc 356.Li cmsghdr
f35d325e 357structure in which the
984263bc 358.Li cmsg_level
f35d325e 359element equals
984263bc 360.Dv IPPROTO_IPV6
f35d325e 361and the
984263bc 362.Li cmsg_type
f35d325e 363element is either
984263bc
MD
364.Dv IPV6_HOPOPTS
365or
366.Dv IPV6_DSTOPTS .
367.Pp
f35d325e 368The
984263bc 369.Fa tptrp
f35d325e
HS
370argument is handled exactly as in the
371.Fn inet6_option_next
372function described above.
7ba324e6 373.Pp
f35d325e 374The
a3220ac5 375.Fn inet6_option_find
f35d325e 376function starts searching for an option of the specified type
984263bc
MD
377beginning after the value of
378.Fa *tptrp .
984263bc 379.\"
0b84df5c 380.Sh EXAMPLES
cabeba47 381RFC 2292 gives comprehensive examples in chapter 6.
0b84df5c 382.\"
984263bc 383.Sh DIAGNOSTICS
f35d325e 384The
984263bc
MD
385.Fn inet6_option_init
386and
387.Fn inet6_option_append
f35d325e 388functions return
984263bc
MD
389.Li 0
390on success or
391.Li -1
392on an error.
393.Pp
f35d325e 394The
984263bc 395.Fn inet6_option_alloc
f35d325e 396function returns
984263bc
MD
397.Dv NULL
398on an error.
399.Pp
f35d325e 400When
984263bc 401.Fn inet6_option_next
f35d325e 402or
984263bc 403.Fn inet6_option_find
f35d325e 404detect an error they return
984263bc
MD
405.Li -1
406setting
407.Fa *tptrp
408to non
409.Dv NULL
410value.
411.\"
984263bc
MD
412.Sh SEE ALSO
413.Rs
414.%A W. Stevens
415.%A M. Thomas
416.%T "Advanced Sockets API for IPv6"
cabeba47 417.%N RFC 2292
984263bc
MD
418.%D February 1998
419.Re
420.Rs
421.%A S. Deering
422.%A R. Hinden
423.%T "Internet Protocol, Version 6 (IPv6) Specification"
cabeba47 424.%N RFC 2460
984263bc
MD
425.%D December 1998
426.Re
427.\"
984263bc 428.Sh STANDARDS
f35d325e 429The functions are documented in
984263bc 430.Dq Advanced Sockets API for IPv6
cabeba47 431(RFC 2292).
984263bc 432.\"
0b84df5c
SW
433.Sh HISTORY
434The implementation first appeared in KAME advanced networking kit.
435.\"