xref: /dragonfly/lib/libc/net/inet6_rthdr_space.3 (revision 8a7bdfea) 
1.\"	$KAME: inet6_rthdr_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $
2.\"	$FreeBSD: src/lib/libc/net/inet6_rthdr_space.3,v 1.14 2005/01/23 16:02:48 gnn Exp $
3.\"	$DragonFly: src/lib/libc/net/inet6_rthdr_space.3,v 1.5 2007/11/23 23:16:36 swildner Exp $
4.\"
5.\" Copyright (C) 2004 WIDE Project.
6.\" All rights reserved.
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.
16.\" 3. Neither the name of the project 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 PROJECT 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 PROJECT 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.Dd December 27, 2004
33.Dt INET6_RTHDR_SPACE 3
34.Os
35.\"
36.Sh NAME
37.Nm inet6_rthdr_space ,
38.Nm inet6_rthdr_init ,
39.Nm inet6_rthdr_add ,
40.Nm inet6_rthdr_lasthop ,
41.Nm inet6_rthdr_reverse ,
42.Nm inet6_rthdr_segments ,
43.Nm inet6_rthdr_getaddr ,
44.Nm inet6_rthdr_getflags
45.Nd IPv6 Routing Header Options Manipulation
46.\"
47.Sh LIBRARY
48.Lb libc
49.Sh SYNOPSIS
50.In sys/types.h
51.In netinet/in.h
52.Ft size_t
53.Fn inet6_rthdr_space "int type" "int segments"
54.Ft "struct cmsghdr *"
55.Fn inet6_rthdr_init "void *bp" "int type"
56.Ft int
57.Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags"
58.Ft int
59.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags"
60.Ft int
61.Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out"
62.Ft int
63.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg"
64.Ft "struct in6_addr *"
65.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index"
66.Ft int
67.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index"
68.\"
69.Sh DESCRIPTION
70.\"The RFC 2292 IPv6 Advanced API has been deprecated in favor of the
71.\"newer, RFC 3542 APIs.
72.\"On platforms that support it, currently only
73.\"FreeBSD, please use the newer API to manipulate routing header
74.\"options.
75.\".Pp
76The RFC 2292 IPv6 Advanced API defined eight functions for
77applications to use for building and parsing routing headers.
78The
79eight functions are split into two groups, the first of which builds
80the header and the second of which can parse it.
81The function prototypes for these functions are all in the
82.In netinet/in.h
83header.
84Although direct manipulation of a routing header is possible
85this set of APIs make it unnecessary and such direct manipulation
86should be avoided so that changes to the underlying structures do not
87break applications.
88.Pp
89Please note that RFC 2292 uses the term
90.Dq segments
91instead of the term
92.Dq addresses
93but they are considered equivalent for this manual page.
94.\"
95.Ss inet6_rthdr_space
96The
97.Fn inet6_rthdr_space
98function returns the number of bytes required to hold a routing header
99of the specified
100.Fa type
101and containing the specified number of
102.Fa segments .
103Only one
104.Fa type
105is supported,
106.Dv IPV6_RTHDR_TYPE_0 ,
107and it can hold from 1 to 23 segments.
108The return value includes the
109size of the cmsghdr structure that precedes the routing header, and
110any required padding.
111.Pp
112A return value of 0 indicates an error.
113Either the type was specified
114incorrectly, or the number of segments was less than one or greater
115than 23.
116.Pp
117Note: The
118.Fn inet6_rthdr_space
119function only returns the size required by the routing header and does
120not allocate memory for the caller.
121.\"
122.Ss inet6_rthdr_init
123The
124.Fn inet6_rthdr_init
125function initializes a buffer, pointed to by
126.Fa bp
127with an appropriate
128.Li cmsghdr
129structure followed by a routing header of the specified
130.Fa type .
131.Pp
132The caller must use the
133.Fn inet6_rthdr_space
134function to determine the size of the buffer, and then allocate that
135buffer before calling
136.Fn inet6_rthdr_init .
137.Pp
138The return value is a pointer to a
139.Li cmsghdr
140structure, which is used as the first argument to the
141.Fn inet6_rthdr_add
142and
143.Fn inet6_rthdr_lasthop
144functions in order to construct the routing header.
145When an error occurs the return value is
146.Dv NULL .
147.\"
148.Ss inet6_rthdr_add
149The
150.Fn inet6_rthdr_add
151function adds the IPv6 address pointed to by
152.Fa addr
153to the end of the
154routing header being constructed and sets the type of this address to the
155value of
156.Fa flags .
157The
158.Fa flags
159must be either
160.Dv IPV6_RTHDR_LOOSE
161or
162.Dv IPV6_RTHDR_STRICT
163indicating whether loose or strict source routing is required.
164.Pp
165When the function succeeds it returns 0, otherwise \-1 is returned.
166.\"
167.Ss inet6_rthdr_lasthop
168The
169.Fn inet6_rthdr_lasthop
170function specifies the strict or loose flag for the final hop of a
171routing header.
172The
173.Fa flags
174must be either
175.Dv IPV6_RTHDR_LOOSE
176or
177.Dv IPV6_RTHDR_STRICT .
178.Pp
179The return value of the function is 0 upon success, and \-1 when an
180error has occurred.
181.Pp
182Please note that a routing header specifying
183.Li N
184intermediate nodes requires
185.Li N+1
186strict or loose flags meaning that
187.Fn inet6_rthdr_add
188must be called
189.Li N
190times and then
191.Fn inet6_rthdr_lasthop
192must be called once.
193.\"
194.Ss inet6_rthdr_reverse
195This function was never implemented.
196.Pp
197The following four functions provide an API for parsing a received
198routing header.
199.\"
200.Ss inet6_rthdr_segments
201The
202.Fn inet6_rthdr_segments
203function returns the number of segments contained in the Routing
204header pointed to by the
205.Fa cmsg
206argument.
207On success the return value is from 1 to 23.
208When an error occurs \-1 is returned.
209.\"
210.Ss inet6_rthdr_getaddr
211The
212.Fn inet6_rthdr_getaddr
213function returns a pointer to the IPv6 address specified by the
214.Fa index
215argument from the routing header pointed to by
216.Fa cmsg .
217The index must be between 1 and the number returned by
218.Fn inet6_rthdr_segments
219described above.
220An application must call
221.Fn inet6_rthdr_segments
222to obtain the number of segments in the routing header.
223.Pp
224If an error occurs the
225.Dv NULL
226is returned.
227.\"
228.Ss inet6_rthdr_getflags
229The
230.Fn inet6_rthdr_getflags
231function returns the flags value of the segment specified by
232.Fa index
233of the routing header pointed to by
234.Fa cmsg .
235The
236.Fa index
237argument must be between 0 and the value returned by
238.Fn inet6_rthdr_segments .
239The return value will be either
240.Dv IPV6_RTHDR_LOOSE
241or
242.Dv IPV6_RTHDR_STRICT
243indicating whether loose or strict source routing was requested for
244that segment.
245.Pp
246When an error occurs \-1 is returned.
247.Pp
248Note: Flags begin at index 0 while segments begin at index 1, to
249maintain consistency with the terminology and figures in RFC 2460.
250.\"
251.Sh EXAMPLES
252RFC 2292 gives comprehensive examples in chapter 8.
253.\"
254.Sh DIAGNOSTICS
255The
256.Fn inet6_rthdr_space
257function returns 0 when an error occurs.
258.Pp
259The
260.Fn inet6_rthdr_add ,
261.Fn inet6_rthdr_lasthop
262functions return 0 on success, and \-1 on error.
263.Pp
264The
265.Fn inet6_rthdr_init
266and
267.Fn inet6_rthdr_getaddr
268functions
269return
270.Dv NULL
271on error.
272.Pp
273The
274.Fn inet6_rthdr_segments
275and
276.Fn inet6_rthdr_getflags
277functions return -1 on error.
278.\"
279.Sh SEE ALSO
280.Rs
281.%A W. Stevens
282.%A M. Thomas
283.%T "Advanced Sockets API for IPv6"
284.%N RFC 2292
285.%D February 1998
286.Re
287.Rs
288.%A S. Deering
289.%A R. Hinden
290.%T "Internet Protocol, Version 6 (IPv6) Specification"
291.%N RFC 2460
292.%D December 1998
293.Re
294.\"
295.Sh HISTORY
296The implementation first appeared in KAME advanced networking kit.
297.\"
298.Sh BUGS
299The
300.Fn inet6_rthdr_reverse
301function was never implemented.
302.\".Pp
303.\"This API is deprecated in favor of
304.\".Xr inet6_rth_space 3
305.\".Sh SEE ALSO
306.\".Xr inet6_rth_space 3
307