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