summaryrefslogtreecommitdiff
path: root/src/lib/libc/net/inet6_rthdr_space.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/net/inet6_rthdr_space.3')
-rw-r--r--src/lib/libc/net/inet6_rthdr_space.3314
1 files changed, 314 insertions, 0 deletions
diff --git a/src/lib/libc/net/inet6_rthdr_space.3 b/src/lib/libc/net/inet6_rthdr_space.3
new file mode 100644
index 0000000000..3287bfe009
--- /dev/null
+++ b/src/lib/libc/net/inet6_rthdr_space.3
@@ -0,0 +1,314 @@
1.\" $OpenBSD: inet6_rthdr_space.3,v 1.20 2007/05/31 19:19:30 jmc Exp $
2.\" $KAME: inet6_rthdr_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $
3.\"
4.\" Copyright (C) 2004 WIDE Project.
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the project nor the names of its contributors
16.\" may be used to endorse or promote products derived from this software
17.\" without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.Dd $Mdocdate: May 31 2007 $
32.Dt INET6_RTHDR_SPACE 3
33.Os
34.\"
35.Sh NAME
36.Nm inet6_rthdr_space ,
37.Nm inet6_rthdr_init ,
38.Nm inet6_rthdr_add ,
39.Nm inet6_rthdr_lasthop ,
40.Nm inet6_rthdr_reverse ,
41.Nm inet6_rthdr_segments ,
42.Nm inet6_rthdr_getaddr ,
43.Nm inet6_rthdr_getflags
44.Nd IPv6 Routing Header Options Manipulation
45.\"
46.Sh SYNOPSIS
47.In sys/types.h
48.In netinet/in.h
49.Ft size_t
50.Fn inet6_rthdr_space "int type" "int segments"
51.Ft "struct cmsghdr *"
52.Fn inet6_rthdr_init "void *bp" "int type"
53.Ft int
54.Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags"
55.Ft int
56.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags"
57.Ft int
58.Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out"
59.Ft int
60.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg"
61.Ft "struct in6_addr *"
62.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index"
63.Ft int
64.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index"
65.\"
66.Sh DESCRIPTION
67.\"The RFC 2292 IPv6 Advanced API has been deprecated in favor of the
68.\"newer, RFC 3542 APIs.
69.\"On platforms that support it, currently only
70.\"FreeBSD, please use the newer API to manipulate routing header
71.\"options.
72.\".Pp
73Note:
74RFC 2292 has been superseded by RFC 3542.
75The use of functions described in this page is deprecated.
76See
77.Xr inet6_rth_space 3 .
78.Pp
79The RFC 2292 IPv6 Advanced API defined eight functions for
80applications to use for building and parsing routing headers.
81The
82eight functions are split into two groups, the first of which builds
83the header and the second of which can parse it.
84The function prototypes for these functions are all in the
85.Aq Pa netinet/in.h
86header.
87Although direct manipulation of a routing header is possible,
88this set of APIs make it unnecessary and such direct manipulation
89should be avoided so that changes to the underlying structures do not
90break applications.
91.Pp
92Please note that RFC 2292 uses the term
93.Dq segments
94instead of the term
95.Dq addresses
96but they are considered equivalent for this manual page.
97.\"
98.Ss inet6_rthdr_space
99The
100.Fn inet6_rthdr_space
101function returns the number of bytes required to hold a routing header
102of the specified
103.Fa type
104and containing the specified number of
105.Fa segments .
106Only one
107.Fa type
108is supported,
109.Dv IPV6_RTHDR_TYPE_0 ,
110and it can hold from 1 to 23 segments.
111The return value includes the
112size of the
113.Vt cmsghdr
114structure that precedes the routing header and
115any required padding.
116.Pp
117A return value of 0 indicates an error.
118Either the type was specified
119incorrectly, or the number of segments was less than one or greater
120than 23.
121.Pp
122Note: The
123.Fn inet6_rthdr_space
124function only returns the size required by the routing header and does
125not allocate memory for the caller.
126.\"
127.Ss inet6_rthdr_init
128The
129.Fn inet6_rthdr_init
130function initializes a buffer, pointed to by
131.Fa bp
132with an appropriate
133.Li cmsghdr
134structure followed by a routing header of the specified
135.Fa type .
136.Pp
137The caller must use the
138.Fn inet6_rthdr_space
139function to determine the size of the buffer, and then allocate that
140buffer before calling
141.Fn inet6_rthdr_init .
142.Pp
143The return value is a pointer to a
144.Li cmsghdr
145structure, which is used as the first argument to the
146.Fn inet6_rthdr_add
147and
148.Fn inet6_rthdr_lasthop
149functions in order to construct the routing header.
150When an error occurs the return value is
151.Dv NULL .
152.\"
153.Ss inet6_rthdr_add
154The
155.Fn inet6_rthdr_add
156function adds the IPv6 address pointed to by
157.Fa addr
158to the end of the
159routing header being constructed and sets the type of this address to the
160value of
161.Fa flags .
162The
163.Fa flags
164must be either
165.Dv IPV6_RTHDR_LOOSE
166or
167.Dv IPV6_RTHDR_STRICT
168indicating whether loose or strict source routing is required.
169.Pp
170When the function succeeds it returns 0, otherwise \-1 is returned.
171.\"
172.Ss inet6_rthdr_lasthop
173The
174.Fn inet6_rthdr_lasthop
175function specifies the strict or loose flag for the final hop of a
176routing header.
177The
178.Fa flags
179argument must be either
180.Dv IPV6_RTHDR_LOOSE
181or
182.Dv IPV6_RTHDR_STRICT .
183.Pp
184The return value of the function is 0 upon success, and \-1 when an
185error has occurred.
186.Pp
187Please note that a routing header specifying
188.Li N
189intermediate nodes requires
190.Li N+1
191strict or loose flags meaning that
192.Fn inet6_rthdr_add
193must be called
194.Li N
195times and then
196.Fn inet6_rthdr_lasthop
197must be called once.
198.\"
199.Ss inet6_rthdr_reverse
200This function was never implemented.
201.Pp
202The following three functions provide an API for parsing a received
203routing header:
204.\"
205.Ss inet6_rthdr_segments
206The
207.Fn inet6_rthdr_segments
208function returns the number of segments contained in the routing
209header pointed to by the
210.Fa cmsg
211argument.
212On success the return value is from 1 to 23.
213When an error occurs, \-1 is returned.
214.\"
215.Ss inet6_rthdr_getaddr
216The
217.Fn inet6_rthdr_getaddr
218function returns a pointer to the IPv6 address specified by the
219.Fa index
220argument from the routing header pointed to by
221.Fa cmsg .
222The index must be between 1 and the number returned by
223.Fn inet6_rthdr_segments ,
224described above.
225An application must call
226.Fn inet6_rthdr_segments
227to obtain the number of segments in the routing header.
228.Pp
229If an error occurs,
230.Dv NULL
231is returned.
232.\"
233.Ss inet6_rthdr_getflags
234The
235.Fn inet6_rthdr_getflags
236function returns the flags value of the segment specified by
237.Fa index
238of the routing header pointed to by
239.Fa cmsg .
240The
241.Fa index
242argument must be between 0 and the value returned by
243.Fn inet6_rthdr_segments .
244The return value will be either
245.Dv IPV6_RTHDR_LOOSE
246or
247.Dv IPV6_RTHDR_STRICT
248indicating whether loose or strict source routing was requested for
249that segment.
250.Pp
251When an error occurs, \-1 is returned.
252.Pp
253Note: Flags begin at index 0 while segments begin at index 1, to
254maintain consistency with the terminology and figures in RFC 2460.
255.\"
256.Sh EXAMPLES
257RFC 2292 gives comprehensive examples in chapter 8.
258.\"
259.Sh DIAGNOSTICS
260The
261.Fn inet6_rthdr_space
262function returns 0 when an error occurs.
263.Pp
264The
265.Fn inet6_rthdr_add
266and
267.Fn inet6_rthdr_lasthop
268functions return 0 on success, and \-1 on error.
269.Pp
270The
271.Fn inet6_rthdr_init
272and
273.Fn inet6_rthdr_getaddr
274functions
275return
276.Dv NULL
277on error.
278.Pp
279The
280.Fn inet6_rthdr_segments
281and
282.Fn inet6_rthdr_getflags
283functions return \-1 on error.
284.\"
285.Sh SEE ALSO
286.Xr inet6 4 ,
287.Xr ip6 4
288.Rs
289.%A W. Stevens
290.%A M. Thomas
291.%T "Advanced Sockets API for IPv6"
292.%N RFC 2292
293.%D February 1998
294.Re
295.Rs
296.%A S. Deering
297.%A R. Hinden
298.%T "Internet Protocol, Version 6 (IPv6) Specification"
299.%N RFC 2460
300.%D December 1998
301.Re
302.\"
303.Sh HISTORY
304This implementation first appeared in the KAME advanced networking kit.
305.\"
306.Sh BUGS
307The
308.Fn inet6_rthdr_reverse
309function was never implemented.
310.\".Pp
311.\"This API is deprecated in favor of
312.\".Xr inet6_rth_space 3
313.\".Sh SEE ALSO
314.\".Xr inet6_rth_space 3
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-04 09:12:24 +0000