xref: /freebsd/lib/libc/net/inet6_opt_init.3 (revision 74bf4e164ba5851606a27d4feff27717452583e5)
1.\"	$KAME: inet6_opt_init.3,v 1.5 2002/10/17 14:13:47 jinmei Exp $
2.\"
3.\" Copyright (C) 2000 WIDE Project.
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the project nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\" $FreeBSD$
31.\"
32.Dd February 5, 2000
33.Dt INET6_OPT_INIT 3
34.Os
35.\"
36.Sh NAME
37.Nm inet6_opt_init ,
38.Nm inet6_opt_append ,
39.Nm inet6_opt_finish ,
40.Nm inet6_opt_set_val ,
41.Nm inet6_opt_next ,
42.Nm inet6_opt_find ,
43.Nm inet6_opt_get_val
44.Nd IPv6 Hop-by-Hop and Destination Options manipulation
45.\"
46.Sh SYNOPSIS
47.In netinet/in.h
48.Ft "int"
49.Fn inet6_opt_init "void *extbuf" "socklen_t extlen"
50.Ft "int"
51.Fn inet6_opt_append "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t len" "u_int8_t align" "void **databufp"
52.Ft "int"
53.Fn inet6_opt_finish "void *extbuf" "socklen_t extlen" "int offset"
54.Ft "int"
55.Fn inet6_opt_set_val "void *databuf" "int offset" "void *val" "socklen_t vallen"
56.Ft "int"
57.Fn inet6_opt_next "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t *typep" "socklen_t *lenp" "void **databufp"
58.Ft "int"
59.Fn inet6_opt_find "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t *lenp" "void **databufp"
60.Ft "int"
61.Fn inet6_opt_get_val "void *databuf" "socklen_t offset" "void *val" "socklen_t vallen"
62.\"
63.Sh DESCRIPTION
64Building and parsing the Hop-by-Hop and Destination options is
65complicated.
66The advanced API therefore defines a set
67of functions to help applications.
68These functions assume the
69formatting rules specified in Appendix B in RFC2460, i.e., that the
70largest field is placed last in the option.
71The function prototypes for
72these functions are all in the
73.In netinet/in.h
74header.
75.\"
76.Ss inet6_opt_init
77The
78.Fn inet6_opt_init
79function
80returns the number of bytes needed for the empty
81extension header, i.e., without any options.
82If
83.Va extbuf
84is not
85.Dv NULL
86it also initializes the extension header to have the correct length
87field.
88In that case if the
89.Fa extlen
90value is not a positive
91(i.e., non-zero)
92multiple of 8 the function fails and returns \-1.
93.\"
94.Ss inet6_opt_append
95The
96.Fn inet6_opt_append
97function
98returns the updated total length taking into account
99adding an option with length
100.Fa len
101and alignment
102.Fa align .
103The
104.Fa offset
105argument
106should be the length returned by
107.Fn inet6_opt_init
108or a previous
109.Fn inet6_opt_append .
110If
111.Fa extbuf
112is not
113.Dv NULL
114then, in addition to returning the length,
115the function inserts any needed pad option, initializes the option
116(setting the type and length fields)
117and returns a pointer to the location for the option content in
118.Fa databufp .
119.Pp
120The
121.Fa type
122argument
123is the 8-bit option type.
124The
125.Fa len
126argument
127is the length of the option data
128(i.e., excluding the option type and option length fields).
129.Pp
130Once
131.Fn inet6_opt_append
132has been called, the application can use the
133databuf directly, or use
134.Fn inet6_opt_set_val
135to specify the content of the option.
136.Pp
137The option type must have a value from 2 to 255, inclusive.
138(0 and 1 are reserved for the Pad1 and PadN options, respectively.)
139.Pp
140The option data length must have a value between 0 and 255,
141inclusive, and is the length of the option data that follows.
142.Pp
143The
144.Fa align
145parameter must have a value of 1, 2, 4, or 8.
146The align value can not exceed the value of
147.Fa len .
148.\"
149.Ss inet6_opt_finish
150The
151.Fn inet6_opt_finish
152function
153returns the updated total length
154taking into account the final padding of the extension header to make
155it a multiple of 8 bytes.
156The
157.Fa offset
158argument
159should be the length returned by
160.Fn inet6_opt_init
161or
162.Fn inet6_opt_append .
163If
164.Fa extbuf
165is not
166.Dv NULL
167the function also
168initializes the option by inserting a Pad1 or PadN option of the
169proper length.
170.Pp
171If the necessary pad does not fit in the extension header buffer the
172function returns \-1.
173.\"
174.Ss inet6_opt_set_val
175The
176.Fn inet6_opt_set_val
177function
178inserts data items of various sizes in the data portion of the option.
179The
180.Fa databuf
181argument
182should be a pointer returned by
183.Fn inet6_opt_append .
184The
185.Fa val
186argument
187should point to the data to be
188inserted.
189The
190.Fa offset
191argument
192specifies where in the data portion of the option
193the value should be inserted; the first byte after the option type
194and length is accessed by specifying an offset of zero.
195.Pp
196The caller should ensure that each field is aligned on its natural
197boundaries as described in Appendix B of RFC2460, but the function
198must not rely on the caller's behavior.
199Even when the alignment requirement is not satisfied,
200the function should just copy the data as required.
201.Pp
202The function returns the offset for the next field
203(i.e.,
204.Fa offset
205+
206.Fa vallen )
207which can be used when composing option content with multiple fields.
208.\"
209.Ss inet6_opt_next
210The
211.Fn inet6_opt_next
212function
213parses received extension headers returning the next
214option.
215The
216.Fa extbuf
217and
218.Fa extlen
219arguments specify the extension header.
220The
221.Fa offset
222argument
223should either be zero (for the first option), or the length returned
224by a previous call to
225.Fn inet6_opt_next
226or
227.Fn inet6_opt_find .
228It specifies the position where to continue scanning the extension
229buffer.
230The next option is returned by updating
231.Fa typep , lenp ,
232and
233.Fa databufp .
234This function returns the updated
235.Dq previous
236length
237computed by advancing past the option that was returned.
238This returned
239.Dq previous
240length can then be passed to subsequent calls to
241.Fn inet6_opt_next .
242This function does not return any PAD1 or PADN options.
243When there are no more options the return value is \-1.
244.\"
245.Ss inet6_opt_get_val
246The
247.Fn inet6_opt_get_val
248function extracts data items of various sizes
249in the data portion of the option.
250The
251.Fa databuf
252argument
253should be a pointer returned by
254.Fn inet6_opt_next
255or
256.Fn inet6_opt_find .
257The
258.Fa val
259argument
260should point to the destination for the extracted data.
261The
262.Fa offset
263argument
264specifies from where in the data portion of the option the value should be
265extracted; the first byte after the option type and length is
266accessed by specifying an offset of zero.
267.Pp
268It is expected that each field is aligned on its natural boundaries
269as described in Appendix B of RFC2460, but the function must not
270rely on the alignment.
271.Pp
272The function returns the offset for the next field
273(i.e.,
274.Fa offset
275+
276.Fa vallen )
277which can be used when extracting option content with
278multiple fields.
279Robust receivers might want to verify alignment before calling
280this function.
281.\"
282.Sh DIAGNOSTICS
283All the functions return
284\-1
285on an error.
286.\"
287.Sh EXAMPLES
288draft-ietf-ipngwg-rfc2292bis-08.txt
289gives comprehensive examples in Section 23.
290.Pp
291KAME also provides examples in the advapitest directory of its kit.
292.\"
293.Sh SEE ALSO
294.Rs
295.%A W. Stevens
296.%A M. Thomas
297.%A E. Nordmark
298.%A T. Jinmei
299.%T "Advanced Sockets API for IPv6"
300.%N draft-ietf-ipngwg-rfc2292bis-08
301.%D October 2002
302.Re
303.Rs
304.%A S. Deering
305.%A R. Hinden
306.%T "Internet Protocol, Version 6 (IPv6) Specification"
307.%N RFC2460
308.%D December 1998
309.Re
310.Sh HISTORY
311The implementation first appeared in KAME advanced networking kit.
312.Sh STANDARDS
313The functions
314are documented in
315.Dq Advanced Sockets API for IPv6
316.Pq draft-ietf-ipngwg-rfc2292bis-08.txt .
317.\"
318.Sh BUGS
319The text was shamelessly copied from internet-drafts for RFC2292bis.
320