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 $
5 .\" Copyright (C) 2004 WIDE Project.
6 .\" All rights reserved.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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
33 .Dt INET6_RTHDR_SPACE 3
37 .Nm inet6_rthdr_space ,
38 .Nm inet6_rthdr_init ,
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
53 .Fn inet6_rthdr_space "int type" "int segments"
54 .Ft "struct cmsghdr *"
55 .Fn inet6_rthdr_init "void *bp" "int type"
57 .Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags"
59 .Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags"
61 .Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out"
63 .Fn inet6_rthdr_segments "const struct cmsghdr *cmsg"
64 .Ft "struct in6_addr *"
65 .Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index"
67 .Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index"
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
76 The RFC 2292 IPv6 Advanced API defined eight functions for
77 applications to use for building and parsing routing headers.
79 eight functions are split into two groups, the first of which builds
80 the header and the second of which can parse it.
81 The function prototypes for these functions are all in the
84 Although direct manipulation of a routing header is possible
85 this set of APIs make it unnecessary and such direct manipulation
86 should be avoided so that changes to the underlying structures do not
89 Please note that RFC 2292 uses the term
93 but they are considered equivalent for this manual page.
98 function returns the number of bytes required to hold a routing header
101 and containing the specified number of
106 .Dv IPV6_RTHDR_TYPE_0 ,
107 and it can hold from 1 to 23 segments.
108 The return value includes the
109 size of the cmsghdr structure that precedes the routing header, and
110 any required padding.
112 A return value of 0 indicates an error.
113 Either the type was specified
114 incorrectly, or the number of segments was less than one or greater
118 .Fn inet6_rthdr_space
119 function only returns the size required by the routing header and does
120 not allocate memory for the caller.
125 function initializes a buffer, pointed to by
129 structure followed by a routing header of the specified
132 The caller must use the
133 .Fn inet6_rthdr_space
134 function to determine the size of the buffer, and then allocate that
135 buffer before calling
136 .Fn inet6_rthdr_init .
138 The return value is a pointer to a
140 structure, which is used as the first argument to the
143 .Fn inet6_rthdr_lasthop
144 functions in order to construct the routing header.
145 When an error occurs the return value is
151 function adds the IPv6 address pointed to by
154 routing header being constructed and sets the type of this address to the
162 .Dv IPV6_RTHDR_STRICT
163 indicating whether loose or strict source routing is required.
165 When the function succeeds it returns 0, otherwise \-1 is returned.
167 .Ss inet6_rthdr_lasthop
169 .Fn inet6_rthdr_lasthop
170 function specifies the strict or loose flag for the final hop of a
177 .Dv IPV6_RTHDR_STRICT .
179 The return value of the function is 0 upon success, and \-1 when an
182 Please note that a routing header specifying
184 intermediate nodes requires
186 strict or loose flags meaning that
191 .Fn inet6_rthdr_lasthop
194 .Ss inet6_rthdr_reverse
195 This function was never implemented.
197 The following four functions provide an API for parsing a received
200 .Ss inet6_rthdr_segments
202 .Fn inet6_rthdr_segments
203 function returns the number of segments contained in the Routing
204 header pointed to by the
207 On success the return value is from 1 to 23.
208 When an error occurs \-1 is returned.
210 .Ss inet6_rthdr_getaddr
212 .Fn inet6_rthdr_getaddr
213 function returns a pointer to the IPv6 address specified by the
215 argument from the routing header pointed to by
217 The index must be between 1 and the number returned by
218 .Fn inet6_rthdr_segments
220 An application must call
221 .Fn inet6_rthdr_segments
222 to obtain the number of segments in the routing header.
224 If an error occurs the
228 .Ss inet6_rthdr_getflags
230 .Fn inet6_rthdr_getflags
231 function returns the flags value of the segment specified by
233 of the routing header pointed to by
237 argument must be between 0 and the value returned by
238 .Fn inet6_rthdr_segments .
239 The return value will be either
242 .Dv IPV6_RTHDR_STRICT
243 indicating whether loose or strict source routing was requested for
246 When an error occurs \-1 is returned.
248 Note: Flags begin at index 0 while segments begin at index 1, to
249 maintain consistency with the terminology and figures in RFC 2460.
252 RFC 2292 gives comprehensive examples in chapter 8.
256 .Fn inet6_rthdr_space
257 function returns 0 when an error occurs.
260 .Fn inet6_rthdr_add ,
261 .Fn inet6_rthdr_lasthop
262 functions return 0 on success, and \-1 on error.
267 .Fn inet6_rthdr_getaddr
274 .Fn inet6_rthdr_segments
276 .Fn inet6_rthdr_getflags
277 functions return -1 on error.
283 .%T "Advanced Sockets API for IPv6"
290 .%T "Internet Protocol, Version 6 (IPv6) Specification"
296 The implementation first appeared in KAME advanced networking kit.
300 .Fn inet6_rthdr_reverse
301 function was never implemented.
303 .\"This API is deprecated in favor of
304 .\".Xr inet6_rth_space 3
306 .\".Xr inet6_rth_space 3