[apple/libinfo.git] / gen.subproj / inet6_opt_init.3

.\"	$KAME: inet6_opt_init.3,v 1.7 2004/12/27 05:08:23 itojun Exp $
.\"
.\" Copyright (C) 2004 WIDE Project.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the project nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/lib/libc/net/inet6_opt_init.3,v 1.10.10.1.4.1 2010/06/14 02:09:06 kensmith Exp $
.\"
.Dd December 23, 2004
.Dt INET6_OPT_INIT 3
.Os
.\"
.Sh NAME
.Nm inet6_opt_init ,
.Nm inet6_opt_append ,
.Nm inet6_opt_finish ,
.Nm inet6_opt_set_val ,
.Nm inet6_opt_next ,
.Nm inet6_opt_find ,
.Nm inet6_opt_get_val
.Nd IPv6 Hop-by-Hop and Destination Options manipulation
.\"
.Sh SYNOPSIS
.In netinet/in.h
.Ft "int"
.Fn inet6_opt_init "void *extbuf" "socklen_t extlen"
.Ft "int"
.Fn inet6_opt_append "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t len" "u_int8_t align" "void **databufp"
.Ft "int"
.Fn inet6_opt_finish "void *extbuf" "socklen_t extlen" "int offset"
.Ft "int"
.Fn inet6_opt_set_val "void *databuf" "int offset" "void *val" "socklen_t vallen"
.Ft "int"
.Fn inet6_opt_next "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t *typep" "socklen_t *lenp" "void **databufp"
.Ft "int"
.Fn inet6_opt_find "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t *lenp" "void **databufp"
.Ft "int"
.Fn inet6_opt_get_val "void *databuf" "int offset" "void *val" "socklen_t vallen"
.\"
.Sh DESCRIPTION
Building and parsing the Hop-by-Hop and Destination options is
complicated.
The advanced sockets API defines a set of functions to
help applications create and manipulate Hop-by-Hop and Destination
options.
This man page describes the functions specified in
IETF Draft RFC3542.
These functions use the
formatting rules specified in Appendix B in RFC2460, i.e., that the
largest field is placed last in the option.
The function prototypes
for these functions are all contained in the
.In netinet/in.h
header file.
.\"
.Ss inet6_opt_init
The
.Fn inet6_opt_init
function
returns the number of bytes needed for an empty
extension header, one without any options.
If the
.Fa extbuf
argument points to a valid section of memory
then the
.Fn inet6_opt_init
function also initializes the extension header's length field.
When attempting to initialize an extension buffer passed in the
.Fa extbuf
argument,
.Fa extlen
must be a positive multiple of 8 or else the function fails and
returns \-1 to the caller.
.\"
.Ss inet6_opt_append
The
.Fn inet6_opt_append
function can perform two different jobs.
When a valid
.Fa extbuf
argument is supplied it appends an option to the extension buffer and
returns the updated total length as well as a pointer to the newly
created option in
.Fa databufp .
If the value
of
.Fa extbuf
is
.Dv NULL
then the
.Fn inet6_opt_append
function only reports what the total length would
be if the option were actually appended.
The
.Fa len
and
.Fa align
arguments specify the length of the option and the required data
alignment which must be used when appending the option.
The
.Fa offset
argument should be the length returned by the
.Fn inet6_opt_init
function or a previous call to
.Fn inet6_opt_append .
.Pp
The
.Fa type
argument is the 8-bit option type.
.Pp
After
.Fn inet6_opt_append
has been called, the application can use the buffer pointed to by
.Fa databufp
directly, or use
.Fn inet6_opt_set_val
to specify the data to be contained in the option.
.Pp
Option types of
.Li 0
and
.Li 1
are reserved for the
.Li Pad1
and
.Li PadN
options.
All other values from 2 through 255 may be used by applications.
.Pp
The length of the option data is contained in an 8-bit value and so
may contain any value from 0 through 255.
.Pp
The
.Fa align
parameter must have a value of 1, 2, 4, or 8 and cannot exceed the
value of
.Fa len .
The alignment values represent no alignment, 16 bit, 32 bit and 64 bit
alignments, respectively.
.\"
.Ss inet6_opt_finish
The
.Fn inet6_opt_finish
function
calculates the final padding necessary to make the extension header a
multiple of 8 bytes, as required by the IPv6 extension header
specification, and returns the extension header's updated total
length.
The
.Fa offset
argument should be the length returned by
.Fn inet6_opt_init
or
.Fn inet6_opt_append .
When
.Fa extbuf
is not
.Dv NULL
the function also sets up the appropriate padding bytes by inserting a
Pad1 or PadN option of the proper length.
.Pp
If the extension header is too small to contain the proper padding
then an error of \-1 is returned to the caller.
.\"
.Ss inet6_opt_set_val
The
.Fn inet6_opt_set_val
function inserts data items of various sizes into the data portion of
the option.
The
.Fa databuf
argument is a pointer to memory that was returned by the
.Fn inet6_opt_append
call and the
.Fa offset
argument specifies where the option should be placed in the
data buffer.
The
.Fa val
argument points to an area of memory containing the data to be
inserted into the extension header, and the
.Fa vallen
argument indicates how much data to copy.
.Pp
The caller should ensure that each field is aligned on its natural
boundaries as described in Appendix B of RFC2460.
.Pp
The function returns the offset for the next field which is calculated as
.Fa offset
+
.Fa vallen
and is used when composing options with multiple fields.
.\"
.Ss inet6_opt_next
The
.Fn inet6_opt_next
function parses received extension headers.
The
.Fa extbuf
and
.Fa extlen
arguments specify the location and length of the extension header
being parsed.
The
.Fa offset
argument should either be zero, for the first option, or the length value
returned by a previous call to
.Fn inet6_opt_next
or
.Fn inet6_opt_find .
The return value specifies the position where to continue scanning the
extension buffer.
The option is returned in the arguments
.Fa typep , lenp ,
and
.Fa databufp ,
which
point to the 8-bit option type, the 8-bit option length and the option
data, respectively.
This function does not return any PAD1 or PADN options.
When an error occurs or there are no more options, the return
value is \-1.
.\"
.Ss inet6_opt_find
The
.Fn inet6_opt_find
function searches the extension buffer for a particular option type,
passed in through the
.Fa type
argument.
If the option is found then the
.Fa lenp
and
.Fa databufp
arguments are updated to point to the option's length and data,
respectively.
The
.Fa extbuf
and
.Fa extlen
arguments
must point to a valid extension buffer and give its length.
The
.Fa offset
argument can be used to search from a location anywhere in the
extension header.
.Ss inet6_opt_get_val
The
.Fn inet6_opt_get_val
function extracts data items of various sizes in the data portion of
the option.
The
.Fa databuf
is a pointer returned by the
.Fn inet6_opt_next
or
.Fn inet6_opt_find
functions.
The
.Fa val
argument points where the data will be extracted.
The
.Fa offset
argument specifies from where in the data portion of the option the
value should be extracted; the first byte of option data is specified
by an offset of zero.
.Pp
It is expected that each field is aligned on its natural boundaries as
described in Appendix B of RFC2460.
.Pp
The function returns the offset for the next field
by calculating
.Fa offset
+
.Fa vallen
which can be used when extracting option content with multiple fields.
Robust receivers must verify alignment before calling this function.
.\"
.Sh RETURN VALUES
All the functions return
\-1
on an error.
.\"
.Sh EXAMPLES
RFC3542 gives comprehensive examples in Section 23.
.Pp
KAME also provides examples in the
.Pa advapitest
directory of its kit.
.\"
.Sh SEE ALSO
.Rs
.%A W. Stevens
.%A M. Thomas
.%A E. Nordmark
.%A T. Jinmei
.%T "Advanced Sockets API for IPv6"
.%N RFC3542
.%D October 2002
.Re
.Rs
.%A S. Deering
.%A R. Hinden
.%T "Internet Protocol, Version 6 (IPv6) Specification"
.%N RFC2460
.%D December 1998
.Re
.Sh STANDARDS
The functions are documented in
.Dq Advanced Sockets API for IPv6
.Pq RFC3542 .
.\"
.Sh HISTORY
The implementation first appeared in KAME advanced networking kit.
Commit	Line	Data
e44d8d47 A	1	.\" $KAME: inet6_opt_init.3,v 1.7 2004/12/27 05:08:23 itojun Exp $
	2	.\"
	3	.\" Copyright (C) 2004 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: src/lib/libc/net/inet6_opt_init.3,v 1.10.10.1.4.1 2010/06/14 02:09:06 kensmith Exp $
	31	.\"
	32	.Dd December 23, 2004
	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" "int offset" "void val" "socklen_t vallen"
	62	.\"
	63	.Sh DESCRIPTION
	64	Building and parsing the Hop-by-Hop and Destination options is
65	complicated.
66	The advanced sockets API defines a set of functions to
67	help applications create and manipulate Hop-by-Hop and Destination
68	options.
69	This man page describes the functions specified in
70	IETF Draft RFC3542.
71	These functions use the
72	formatting rules specified in Appendix B in RFC2460, i.e., that the
73	largest field is placed last in the option.
74	The function prototypes
75	for these functions are all contained in the
76	.In netinet/in.h
77	header file.
78	.\"
79	.Ss inet6_opt_init
80	The
81	.Fn inet6_opt_init
82	function
83	returns the number of bytes needed for an empty
84	extension header, one without any options.
85	If the
86	.Fa extbuf
87	argument points to a valid section of memory
88	then the
89	.Fn inet6_opt_init
90	function also initializes the extension header's length field.
91	When attempting to initialize an extension buffer passed in the
92	.Fa extbuf
93	argument,
94	.Fa extlen
95	must be a positive multiple of 8 or else the function fails and
96	returns \-1 to the caller.
97	.\"
98	.Ss inet6_opt_append
99	The
100	.Fn inet6_opt_append
101	function can perform two different jobs.
102	When a valid
103	.Fa extbuf
104	argument is supplied it appends an option to the extension buffer and
105	returns the updated total length as well as a pointer to the newly
106	created option in
107	.Fa databufp .
108	If the value
109	of
110	.Fa extbuf
111	is
112	.Dv NULL
113	then the
114	.Fn inet6_opt_append
115	function only reports what the total length would
116	be if the option were actually appended.
117	The
118	.Fa len
119	and
120	.Fa align
121	arguments specify the length of the option and the required data
122	alignment which must be used when appending the option.
123	The
124	.Fa offset
125	argument should be the length returned by the
126	.Fn inet6_opt_init
127	function or a previous call to
128	.Fn inet6_opt_append .
129	.Pp
130	The
131	.Fa type
132	argument is the 8-bit option type.
133	.Pp
134	After
135	.Fn inet6_opt_append
136	has been called, the application can use the buffer pointed to by
137	.Fa databufp
138	directly, or use
139	.Fn inet6_opt_set_val
140	to specify the data to be contained in the option.
141	.Pp
142	Option types of
143	.Li 0
144	and
145	.Li 1
146	are reserved for the
147	.Li Pad1
148	and
149	.Li PadN
150	options.
151	All other values from 2 through 255 may be used by applications.
152	.Pp
153	The length of the option data is contained in an 8-bit value and so
154	may contain any value from 0 through 255.
155	.Pp
156	The
157	.Fa align
158	parameter must have a value of 1, 2, 4, or 8 and cannot exceed the
159	value of
160	.Fa len .
161	The alignment values represent no alignment, 16 bit, 32 bit and 64 bit
162	alignments, respectively.
163	.\"
164	.Ss inet6_opt_finish
165	The
166	.Fn inet6_opt_finish
167	function
168	calculates the final padding necessary to make the extension header a
169	multiple of 8 bytes, as required by the IPv6 extension header
170	specification, and returns the extension header's updated total
171	length.
172	The
173	.Fa offset
174	argument should be the length returned by
175	.Fn inet6_opt_init
176	or
177	.Fn inet6_opt_append .
178	When
179	.Fa extbuf
180	is not
181	.Dv NULL
182	the function also sets up the appropriate padding bytes by inserting a
183	Pad1 or PadN option of the proper length.
184	.Pp
185	If the extension header is too small to contain the proper padding
186	then an error of \-1 is returned to the caller.
187	.\"
188	.Ss inet6_opt_set_val
189	The
190	.Fn inet6_opt_set_val
191	function inserts data items of various sizes into the data portion of
192	the option.
193	The
194	.Fa databuf
195	argument is a pointer to memory that was returned by the
196	.Fn inet6_opt_append
197	call and the
198	.Fa offset
199	argument specifies where the option should be placed in the
200	data buffer.
201	The
202	.Fa val
203	argument points to an area of memory containing the data to be
204	inserted into the extension header, and the
205	.Fa vallen
206	argument indicates how much data to copy.
207	.Pp
208	The caller should ensure that each field is aligned on its natural
209	boundaries as described in Appendix B of RFC2460.
210	.Pp
211	The function returns the offset for the next field which is calculated as
212	.Fa offset
213	+
214	.Fa vallen
215	and is used when composing options with multiple fields.
216	.\"
217	.Ss inet6_opt_next
218	The
219	.Fn inet6_opt_next
220	function parses received extension headers.
221	The
222	.Fa extbuf
223	and
224	.Fa extlen
225	arguments specify the location and length of the extension header
226	being parsed.
227	The
228	.Fa offset
229	argument should either be zero, for the first option, or the length value
230	returned by a previous call to
231	.Fn inet6_opt_next
232	or
233	.Fn inet6_opt_find .
234	The return value specifies the position where to continue scanning the
235	extension buffer.
236	The option is returned in the arguments
237	.Fa typep , lenp ,
238	and
239	.Fa databufp ,
240	which
241	point to the 8-bit option type, the 8-bit option length and the option
242	data, respectively.
243	This function does not return any PAD1 or PADN options.
244	When an error occurs or there are no more options, the return
245	value is \-1.
246	.\"
247	.Ss inet6_opt_find
248	The
249	.Fn inet6_opt_find
250	function searches the extension buffer for a particular option type,
251	passed in through the
252	.Fa type
253	argument.
254	If the option is found then the
255	.Fa lenp
256	and
257	.Fa databufp
258	arguments are updated to point to the option's length and data,
259	respectively.
260	The
261	.Fa extbuf
262	and
263	.Fa extlen
264	arguments
265	must point to a valid extension buffer and give its length.
266	The
267	.Fa offset
268	argument can be used to search from a location anywhere in the
269	extension header.
270	.Ss inet6_opt_get_val
271	The
272	.Fn inet6_opt_get_val
273	function extracts data items of various sizes in the data portion of
274	the option.
275	The
276	.Fa databuf
277	is a pointer returned by the
278	.Fn inet6_opt_next
279	or
280	.Fn inet6_opt_find
281	functions.
282	The
283	.Fa val
284	argument points where the data will be extracted.
285	The
286	.Fa offset
287	argument specifies from where in the data portion of the option the
288	value should be extracted; the first byte of option data is specified
289	by an offset of zero.
290	.Pp
291	It is expected that each field is aligned on its natural boundaries as
292	described in Appendix B of RFC2460.
293	.Pp
294	The function returns the offset for the next field
295	by calculating
296	.Fa offset
297	+
298	.Fa vallen
299	which can be used when extracting option content with multiple fields.
300	Robust receivers must verify alignment before calling this function.
301	.\"
302	.Sh RETURN VALUES
303	All the functions return
304	\-1
305	on an error.
306	.\"
307	.Sh EXAMPLES
308	RFC3542 gives comprehensive examples in Section 23.
309	.Pp
310	KAME also provides examples in the
311	.Pa advapitest
312	directory of its kit.
313	.\"
314	.Sh SEE ALSO
315	.Rs
316	.%A W. Stevens
317	.%A M. Thomas
318	.%A E. Nordmark
319	.%A T. Jinmei
320	.%T "Advanced Sockets API for IPv6"
321	.%N RFC3542
322	.%D October 2002
323	.Re
324	.Rs
325	.%A S. Deering
326	.%A R. Hinden
327	.%T "Internet Protocol, Version 6 (IPv6) Specification"
328	.%N RFC2460
329	.%D December 1998
330	.Re
331	.Sh STANDARDS
332	The functions are documented in
333	.Dq Advanced Sockets API for IPv6
334	.Pq RFC3542 .
335	.\"
336	.Sh HISTORY
337	The implementation first appeared in KAME advanced networking kit.