]> git.saurik.com Git - apple/libinfo.git/blob - gen.subproj/inet6_rth_space.3
Libinfo-449.1.3.tar.gz
[apple/libinfo.git] / gen.subproj / inet6_rth_space.3
1 .\" $KAME: inet6_rth_space.3,v 1.7 2005/01/05 03:00:44 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_rth_space.3,v 1.10.10.1.4.1 2010/06/14 02:09:06 kensmith Exp $
31 .\"
32 .Dd December 24, 2004
33 .Dt INET6_RTH_SPACE 3
34 .Os
35 .\"
36 .Sh NAME
37 .Nm inet6_rth_space ,
38 .Nm inet6_rth_init ,
39 .Nm inet6_rth_add ,
40 .Nm inet6_rth_reverse ,
41 .Nm inet6_rth_segments ,
42 .Nm inet6_rth_getaddr
43 .Nd IPv6 Routing Header Options manipulation
44 .\"
45 .Sh SYNOPSIS
46 .Fd #include <netinet6/in6.h>
47 .Ft socklen_t
48 .Fn inet6_rth_space "int" "int"
49 .Ft "void *"
50 .Fn inet6_rth_init "void *" "socklen_t" "int" "int"
51 .Ft int
52 .Fn inet6_rth_add "void *" "const struct in6_addr *"
53 .Ft int
54 .Fn inet6_rth_reverse "const void *" "void *"
55 .Ft int
56 .Fn inet6_rth_segments "const void *"
57 .Ft "struct in6_addr *"
58 .Fn inet6_rth_getaddr "const void *" "int"
59 .\"
60 .Sh DESCRIPTION
61 The IPv6 Advanced API, RFC 3542, defines the functions that an
62 application calls to build and examine IPv6 Routing headers.
63 Routing headers are used to perform source routing in IPv6 networks.
64 The RFC uses the word
65 .Dq segments
66 to describe addresses and that is the term used here as well.
67 All of the functions are defined in the
68 .In netinet/in.h
69 header file.
70 The functions described in this manual page all operate
71 on routing header structures which are defined in
72 .In netinet/ip6.h
73 but which should not need to be modified outside the use of this API.
74 The size and shape of the route header structures may change, so using
75 the APIs is a more portable, long term, solution.
76 .Pp
77 The functions in the API are split into two groups, those that build a
78 routing header and those that parse a received routing header.
79 We will describe the builder functions followed by the parser functions.
80 .Ss inet6_rth_space
81 The
82 .Fn inet6_rth_space
83 function returns the number of bytes required to hold a Routing Header
84 of the type, specified in the
85 .Fa type
86 argument and containing the number of addresses specified in the
87 .Fa segments
88 argument.
89 When the type is
90 .Dv IPV6_RTHDR_TYPE_0
91 the number of segments must be from 0 through 127.
92 Routing headers of type
93 .Dv IPV6_RTHDR_TYPE_2
94 contain only one segment, and are only used with Mobile IPv6.
95 The return value from this function is the number of bytes required to
96 store the routing header.
97 If the value 0 is returned then either the
98 route header type was not recognized or another error occurred.
99 .Ss inet6_rth_init
100 The
101 .Fn inet6_rth_init
102 function initializes the pre-allocated buffer pointed to by
103 .Fa bp
104 to contain a routing header of the specified type The
105 .Fa bp_len
106 argument is used to verify that the buffer is large enough.
107 The caller must allocate the buffer pointed to by bp.
108 The necessary buffer size should be determined by calling
109 .Fn inet6_rth_space
110 described in the previous sections.
111 .Pp
112 The
113 .Fn inet6_rth_init
114 function returns a pointer to
115 .Fa bp
116 on success and
117 .Dv NULL
118 when there is an error.
119 .Ss inet6_rth_add
120 The
121 .Fn inet6_rth_add
122 function adds the IPv6 address pointed to by
123 .Fa addr
124 to the end of the routing header being constructed.
125 .Pp
126 A successful addition results in the function returning 0, otherwise
127 \-1 is returned.
128 .Ss inet6_rth_reverse
129 The
130 .Fn inet6_rth_reverse
131 function takes a routing header, pointed to by the
132 argument
133 .Fa in ,
134 and writes a new routing header into the argument pointed to by
135 .Fa out .
136 The routing header at that sends datagrams along the reverse of that
137 route.
138 Both arguments are allowed to point to the same buffer meaning
139 that the reversal can occur in place.
140 .Pp
141 The return value of the function is 0 on success, or \-1 when
142 there is an error.
143 .\"
144 .Pp
145 The next set of functions operate on a routing header that the
146 application wants to parse.
147 In the usual case such a routing header
148 is received from the network, although these functions can also be
149 used with routing headers that the application itself created.
150 .Ss inet6_rth_segments
151 The
152 .Fn inet6_rth_segments
153 function returns the number of segments contained in the
154 routing header pointed to by
155 .Fa bp .
156 The return value is the number of segments contained in the routing
157 header, or \-1 if an error occurred.
158 It is not an error for 0 to be
159 returned as a routing header may contain 0 segments.
160 .\"
161 .Ss inet6_rth_getaddr
162 The
163 .Fn inet6_rth_getaddr
164 function is used to retrieve a single address from a routing header.
165 The
166 .Fa index
167 is the location in the routing header from which the application wants
168 to retrieve an address.
169 The
170 .Fa index
171 parameter must have a value between 0 and one less than the number of
172 segments present in the routing header.
173 The
174 .Fn inet6_rth_segments
175 function, described in the last section, should be used to determine
176 the total number of segments in the routing header.
177 The
178 .Fn inet6_rth_getaddr
179 function returns a pointer to an IPv6 address on success or
180 .Dv NULL
181 when an error has occurred.
182 .\"
183 .Sh EXAMPLES
184 RFC 3542 gives extensive examples in Section 21, Appendix B.
185 .Pp
186 KAME also provides examples in the advapitest directory of its kit.
187 .\"
188 .Sh DIAGNOSTICS
189 The
190 .Fn inet6_rth_space
191 and
192 .Fn inet6_rth_getaddr
193 functions return 0 on errors.
194 .Pp
195 The
196 .Fn inet6_rthdr_init
197 function returns
198 .Dv NULL
199 on error.
200 The
201 .Fn inet6_rth_add
202 and
203 .Fn inet6_rth_reverse
204 functions return 0 on success, or \-1 upon an error.
205 .\"
206 .Sh SEE ALSO
207 .Rs
208 .%A W. Stevens
209 .%A M. Thomas
210 .%A E. Nordmark
211 .%A T. Jinmei
212 .%T "Advanced Sockets API for IPv6"
213 .%N RFC 3542
214 .%D May 2003
215 .Re
216 .Rs
217 .%A S. Deering
218 .%A R. Hinden
219 .%T "Internet Protocol, Version 6 (IPv6) Specification"
220 .%N RFC2460
221 .%D December 1998
222 .Re
223 .Sh HISTORY
224 The implementation first appeared in KAME advanced networking kit.