[apple/libc.git] / net / inet6_rthdr_space.3

.\" Copyright (c) 1983, 1987, 1991, 1993
.\"	The Regents of the University of California.  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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University 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 REGENTS 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 REGENTS 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.
.\"
.\"     $Id: inet6_rthdr_space.3,v 1.1 2001/12/18 01:21:22 bbraun Exp $
.\" $FreeBSD: src/lib/libc/net/inet6_rthdr_space.3,v 1.8 2001/10/01 16:08:55 ru Exp $
.\"
.Dd December 10, 1999
.Dt INET6_RTHDR_SPACE 3
.Os
.\"
.Sh NAME
.Nm inet6_rthdr_space ,
.Nm inet6_rthdr_init ,
.Nm inet6_rthdr_add ,
.Nm inet6_rthdr_lasthop ,
.Nm inet6_rthdr_reverse ,
.Nm inet6_rthdr_segments ,
.Nm inet6_rthdr_getaddr ,
.Nm inet6_rthdr_getflags
.Nd IPv6 Routing Header Options manipulation
.\"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/types.h
.In netinet/in.h
.Ft size_t
.Fn inet6_rthdr_space "int type" "int segments"
.Ft "struct cmsghdr *"
.Fn inet6_rthdr_init "void *bp" "int type"
.Ft int
.Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags"
.Ft int
.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags"
.Ft int
.Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out"
.Ft int
.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg"
.Ft "struct in6_addr *"
.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index"
.Ft int
.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index"
.\"
.Sh DESCRIPTION
RFC2292 IPv6 advanced API defines eight
functions that the application calls to build and examine a Routing
header.  Four functions build a Routing header:
.Bl -hang
.It Fn inet6_rthdr_space
return #bytes required for ancillary data
.It Fn inet6_rthdr_init
initialize ancillary data for Routing header
.It Fn inet6_rthdr_add
add IPv6 address & flags to Routing header
.It Fn inet6_rthdr_lasthop
specify the flags for the final hop
.El
.Pp
Four functions deal with a returned Routing header:
.Bl -hang
.It Fn inet6_rthdr_reverse
reverse a Routing header
.It Fn inet6_rthdr_segments
return #segments in a Routing header
.It Fn inet6_rthdr_getaddr
fetch one address from a Routing header
.It Fn inet6_rthdr_getflags
fetch one flag from a Routing header
.El
.Pp
The function prototypes for these functions are all in the
.Aq Li netinet/in.h
header.
.\"
.Ss inet6_rthdr_space
This function returns the number of bytes required to hold a Routing
header of the specified
.Fa type
containing the specified number of
.Fa segments
(addresses).
For an IPv6 Type 0 Routing header, the number
of segments must be between 1 and 23, inclusive.  The return value
includes the size of the cmsghdr structure that precedes the Routing
header, and any required padding.
.Pp
If the return value is 0, then either the type of the Routing header
is not supported by this implementation or the number of segments is
invalid for this type of Routing header.
.Pp
Note: This function returns the size but does not allocate the space
required for the ancillary data.
This allows an application to
allocate a larger buffer, if other ancillary data objects are
desired, since all the ancillary data objects must be specified to
.Xr sendmsg 2
as a single
.Li msg_control
buffer.
.\"
.Ss inet6_rthdr_init
This function initializes the buffer pointed to by
.Fa bp
to contain a
.Li cmsghdr
structure followed by a Routing header of the specified
.Fa type .
The
.Li cmsg_len
member of the
.Li cmsghdr
structure is initialized to the
size of the structure plus the amount of space required by the
Routing header.
The
.Li cmsg_level
and
.Li cmsg_type
members are also initialized as required.
.Pp
The caller must allocate the buffer and its size can be determined by
calling
.Fn inet6_rthdr_space .
.Pp
Upon success the return value is the pointer to the
.Li cmsghdr
structure, and this is then used as the first argument to the next
two functions.
Upon an error the return value is
.Dv NULL .
.\"
.Ss inet6_rthdr_add
This function adds the address pointed to by
.Fa addr
to the end of the
Routing header being constructed and sets the type of this hop to the
value of
.Fa flags .
For an IPv6 Type 0 Routing header,
.Fa flags
must be
either
.Dv IPV6_RTHDR_LOOSE
or
.Dv IPV6_RTHDR_STRICT .
.Pp
If successful, the
.Li cmsg_len
member of the
.Li cmsghdr
structure is
updated to account for the new address in the Routing header and the
return value of the function is 0.
Upon an error the return value of
the function is -1.
.\"
.Ss inet6_rthdr_lasthop
This function specifies the Strict/Loose flag for the final hop of a
Routing header.
For an IPv6 Type 0 Routing header,
.Fa flags
must be either
.Dv IPV6_RTHDR_LOOSE
or
.Dv IPV6_RTHDR_STRICT .
.Pp
The return value of the function is 0 upon success, or -1 upon an error.
.Pp
Notice that a Routing header specifying
.Li N
intermediate nodes requires
.Li N+1
Strict/Loose flags.
This requires
.Li N
calls to
.Fn inet6_rthdr_add
followed by one call to
.Fn inet6_rthdr_lasthop .
.\"
.Ss inet6_rthdr_reverse
This function is not yet implemented.
When implemented, this should behave as follows.
.Pp
This function takes a Routing header that was received as ancillary
data
(pointed to by the first argument,
.Fa in )
and writes a new Routing
header that sends datagrams along the reverse of that route.
Both
arguments are allowed to point to the same buffer
(that is, the reversal can occur in place).
.Pp
The return value of the function is 0 on success, or -1 upon an
error.
.\"
.Ss inet6_rthdr_segments
This function returns the number of segments
(addresses)
contained in
the Routing header described by
.Fa cmsg .
On success the return value is
between 1 and 23, inclusive.
The return value of the function is -1 upon an error.
.\"
.Ss inet6_rthdr_getaddr
This function returns a pointer to the IPv6 address specified by
.Fa index
(which must have a value between 1 and the value returned by
.Fn inet6_rthdr_segments )
in the Routing header described by
.Fa cmsg .
An
application should first call
.Fn inet6_rthdr_segments
to obtain the number of segments in the Routing header.
.Pp
Upon an error the return value of the function is
.Dv NULL .
.\"
.Ss inet6_rthdr_getflags
This function returns the flags value specified by
.Fa index
(which must
have a value between 0 and the value returned by
.Fn inet6_rthdr_segments )
in the Routing header described by
.Fa cmsg .
For an IPv6 Type 0 Routing header the return value will be either
.Dv IPV6_RTHDR_LOOSE
or
.Dv IPV6_RTHDR_STRICT .
.Pp
Upon an error the return value of the function is -1.
.Pp
Note: Addresses are indexed starting at 1, and flags starting at 0,
to maintain consistency with the terminology and figures in RFC2460.
.\"
.Sh DIAGNOSTICS
.Fn inet6_rthdr_space
returns 0 on errors.
.Pp
.Fn inet6_rthdr_add ,
.Fn inet6_rthdr_lasthop
and
.Fn inet6_rthdr_reverse
return 0 on success, and returns -1 on error.
.Pp
.Fn inet6_rthdr_init
and
.Fn inet6_rthdr_getaddr
return
.Dv NULL
on error.
.Pp
.Fn inet6_rthdr_segments
and
.Fn inet6_rthdr_getflags
return -1 on error.
.\"
.Sh EXAMPLES
RFC2292 gives comprehensive examples in chapter 8.
.\"
.Sh SEE ALSO
.Rs
.%A W. Stevens
.%A M. Thomas
.%T "Advanced Sockets API for IPv6"
.%N RFC2292
.%D February 1998
.Re
.Rs
.%A S. Deering
.%A R. Hinden
.%T "Internet Protocol, Version 6 (IPv6) Specification"
.%N RFC2460
.%D December 1998
.Re
.\"
.Sh HISTORY
The implementation first appeared in KAME advanced networking kit.
.\"
.Sh STANDARDS
The functions
are documented in
.Dq Advanced Sockets API for IPv6
(RFC2292).
.\"
.Sh BUGS
The text was shamelessly copied from RFC2292.
.Pp
.Fn inet6_rthdr_reverse
is not implemented yet.
Commit	Line	Data
5b2abdfb A	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_rthdr_space.3,v 1.1 2001/12/18 01:21:22 bbraun Exp $
	33	.\" $FreeBSD: src/lib/libc/net/inet6_rthdr_space.3,v 1.8 2001/10/01 16:08:55 ru Exp $
	34	.\"
	35	.Dd December 10, 1999
	36	.Dt INET6_RTHDR_SPACE 3
	37	.Os
	38	.\"
	39	.Sh NAME
	40	.Nm inet6_rthdr_space ,
	41	.Nm inet6_rthdr_init ,
	42	.Nm inet6_rthdr_add ,
	43	.Nm inet6_rthdr_lasthop ,
	44	.Nm inet6_rthdr_reverse ,
	45	.Nm inet6_rthdr_segments ,
	46	.Nm inet6_rthdr_getaddr ,
	47	.Nm inet6_rthdr_getflags
	48	.Nd IPv6 Routing Header Options manipulation
	49	.\"
	50	.Sh LIBRARY
	51	.Lb libc
	52	.Sh SYNOPSIS
	53	.In sys/types.h
	54	.In netinet/in.h
	55	.Ft size_t
	56	.Fn inet6_rthdr_space "int type" "int segments"
	57	.Ft "struct cmsghdr *"
	58	.Fn inet6_rthdr_init "void *bp" "int type"
	59	.Ft int
	60	.Fn inet6_rthdr_add "struct cmsghdr cmsg" "const struct in6_addr addr" "unsigned int flags"
	61	.Ft int
	62	.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags"
	63	.Ft int
	64	.Fn inet6_rthdr_reverse "const struct cmsghdr in" "struct cmsghdr out"
65	.Ft int
66	.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg"
67	.Ft "struct in6_addr *"
68	.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index"
69	.Ft int
70	.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index"
71	.\"
72	.Sh DESCRIPTION
73	RFC2292 IPv6 advanced API defines eight
74	functions that the application calls to build and examine a Routing
75	header. Four functions build a Routing header:
76	.Bl -hang
77	.It Fn inet6_rthdr_space
78	return #bytes required for ancillary data
79	.It Fn inet6_rthdr_init
80	initialize ancillary data for Routing header
81	.It Fn inet6_rthdr_add
82	add IPv6 address & flags to Routing header
83	.It Fn inet6_rthdr_lasthop
84	specify the flags for the final hop
85	.El
86	.Pp
87	Four functions deal with a returned Routing header:
88	.Bl -hang
89	.It Fn inet6_rthdr_reverse
90	reverse a Routing header
91	.It Fn inet6_rthdr_segments
92	return #segments in a Routing header
93	.It Fn inet6_rthdr_getaddr
94	fetch one address from a Routing header
95	.It Fn inet6_rthdr_getflags
96	fetch one flag from a Routing header
97	.El
98	.Pp
99	The function prototypes for these functions are all in the
100	.Aq Li netinet/in.h
101	header.
102	.\"
103	.Ss inet6_rthdr_space
104	This function returns the number of bytes required to hold a Routing
105	header of the specified
106	.Fa type
107	containing the specified number of
108	.Fa segments
109	(addresses).
110	For an IPv6 Type 0 Routing header, the number
111	of segments must be between 1 and 23, inclusive. The return value
112	includes the size of the cmsghdr structure that precedes the Routing
113	header, and any required padding.
114	.Pp
115	If the return value is 0, then either the type of the Routing header
116	is not supported by this implementation or the number of segments is
117	invalid for this type of Routing header.
118	.Pp
119	Note: This function returns the size but does not allocate the space
120	required for the ancillary data.
121	This allows an application to
122	allocate a larger buffer, if other ancillary data objects are
123	desired, since all the ancillary data objects must be specified to
124	.Xr sendmsg 2
125	as a single
126	.Li msg_control
127	buffer.
128	.\"
129	.Ss inet6_rthdr_init
130	This function initializes the buffer pointed to by
131	.Fa bp
132	to contain a
133	.Li cmsghdr
134	structure followed by a Routing header of the specified
135	.Fa type .
136	The
137	.Li cmsg_len
138	member of the
139	.Li cmsghdr
140	structure is initialized to the
141	size of the structure plus the amount of space required by the
142	Routing header.
143	The
144	.Li cmsg_level
145	and
146	.Li cmsg_type
147	members are also initialized as required.
148	.Pp
149	The caller must allocate the buffer and its size can be determined by
150	calling
151	.Fn inet6_rthdr_space .
152	.Pp
153	Upon success the return value is the pointer to the
154	.Li cmsghdr
155	structure, and this is then used as the first argument to the next
156	two functions.
157	Upon an error the return value is
158	.Dv NULL .
159	.\"
160	.Ss inet6_rthdr_add
161	This function adds the address pointed to by
162	.Fa addr
163	to the end of the
164	Routing header being constructed and sets the type of this hop to the
165	value of
166	.Fa flags .
167	For an IPv6 Type 0 Routing header,
168	.Fa flags
169	must be
170	either
171	.Dv IPV6_RTHDR_LOOSE
172	or
173	.Dv IPV6_RTHDR_STRICT .
174	.Pp
175	If successful, the
176	.Li cmsg_len
177	member of the
178	.Li cmsghdr
179	structure is
180	updated to account for the new address in the Routing header and the
181	return value of the function is 0.
182	Upon an error the return value of
183	the function is -1.
184	.\"
185	.Ss inet6_rthdr_lasthop
186	This function specifies the Strict/Loose flag for the final hop of a
187	Routing header.
188	For an IPv6 Type 0 Routing header,
189	.Fa flags
190	must be either
191	.Dv IPV6_RTHDR_LOOSE
192	or
193	.Dv IPV6_RTHDR_STRICT .
194	.Pp
195	The return value of the function is 0 upon success, or -1 upon an error.
196	.Pp
197	Notice that a Routing header specifying
198	.Li N
199	intermediate nodes requires
200	.Li N+1
201	Strict/Loose flags.
202	This requires
203	.Li N
204	calls to
205	.Fn inet6_rthdr_add
206	followed by one call to
207	.Fn inet6_rthdr_lasthop .
208	.\"
209	.Ss inet6_rthdr_reverse
210	This function is not yet implemented.
211	When implemented, this should behave as follows.
212	.Pp
213	This function takes a Routing header that was received as ancillary
214	data
215	(pointed to by the first argument,
216	.Fa in )
217	and writes a new Routing
218	header that sends datagrams along the reverse of that route.
219	Both
220	arguments are allowed to point to the same buffer
221	(that is, the reversal can occur in place).
222	.Pp
223	The return value of the function is 0 on success, or -1 upon an
224	error.
225	.\"
226	.Ss inet6_rthdr_segments
227	This function returns the number of segments
228	(addresses)
229	contained in
230	the Routing header described by
231	.Fa cmsg .
232	On success the return value is
233	between 1 and 23, inclusive.
234	The return value of the function is -1 upon an error.
235	.\"
236	.Ss inet6_rthdr_getaddr
237	This function returns a pointer to the IPv6 address specified by
238	.Fa index
239	(which must have a value between 1 and the value returned by
240	.Fn inet6_rthdr_segments )
241	in the Routing header described by
242	.Fa cmsg .
243	An
244	application should first call
245	.Fn inet6_rthdr_segments
246	to obtain the number of segments in the Routing header.
247	.Pp
248	Upon an error the return value of the function is
249	.Dv NULL .
250	.\"
251	.Ss inet6_rthdr_getflags
252	This function returns the flags value specified by
253	.Fa index
254	(which must
255	have a value between 0 and the value returned by
256	.Fn inet6_rthdr_segments )
257	in the Routing header described by
258	.Fa cmsg .
259	For an IPv6 Type 0 Routing header the return value will be either
260	.Dv IPV6_RTHDR_LOOSE
261	or
262	.Dv IPV6_RTHDR_STRICT .
263	.Pp
264	Upon an error the return value of the function is -1.
265	.Pp
266	Note: Addresses are indexed starting at 1, and flags starting at 0,
267	to maintain consistency with the terminology and figures in RFC2460.
268	.\"
269	.Sh DIAGNOSTICS
270	.Fn inet6_rthdr_space
271	returns 0 on errors.
272	.Pp
273	.Fn inet6_rthdr_add ,
274	.Fn inet6_rthdr_lasthop
275	and
276	.Fn inet6_rthdr_reverse
277	return 0 on success, and returns -1 on error.
278	.Pp
279	.Fn inet6_rthdr_init
280	and
281	.Fn inet6_rthdr_getaddr
282	return
283	.Dv NULL
284	on error.
285	.Pp
286	.Fn inet6_rthdr_segments
287	and
288	.Fn inet6_rthdr_getflags
289	return -1 on error.
290	.\"
291	.Sh EXAMPLES
292	RFC2292 gives comprehensive examples in chapter 8.
293	.\"
294	.Sh SEE ALSO
295	.Rs
296	.%A W. Stevens
297	.%A M. Thomas
298	.%T "Advanced Sockets API for IPv6"
299	.%N RFC2292
300	.%D February 1998
301	.Re
302	.Rs
303	.%A S. Deering
304	.%A R. Hinden
305	.%T "Internet Protocol, Version 6 (IPv6) Specification"
306	.%N RFC2460
307	.%D December 1998
308	.Re
309	.\"
310	.Sh HISTORY
311	The implementation first appeared in KAME advanced networking kit.
312	.\"
313	.Sh STANDARDS
314	The functions
315	are documented in
316	.Dq Advanced Sockets API for IPv6
317	(RFC2292).
318	.\"
319	.Sh BUGS
320	The text was shamelessly copied from RFC2292.
321	.Pp
322	.Fn inet6_rthdr_reverse
323	is not implemented yet.