Annotation of src/lib/libc/inet/inet6_rthdr_space.3, Revision 1.3
1.3 ! wiz 1: .\" $NetBSD: inet6_rthdr_space.3,v 1.2 2010/03/22 19:30:54 joerg Exp $
1.1 christos 2: .\" $KAME: inet6_rthdr_space.3,v 1.8 2000/05/17 14:30:15 itojun Exp $
3: .\"
4: .\" Copyright (c) 1983, 1987, 1991, 1993
5: .\" The Regents of the University of California. 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 University 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 REGENTS 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 REGENTS 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 December 10, 1999
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 netinet/in.h
48: .Ft size_t
49: .Fn inet6_rthdr_space "int type" "int segments"
50: .Ft "struct cmsghdr *"
51: .Fn inet6_rthdr_init "void *bp" "int type"
52: .Ft int
53: .Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags"
54: .Ft int
55: .Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags"
56: .Ft int
57: .Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out"
58: .Ft int
59: .Fn inet6_rthdr_segments "const struct cmsghdr *cmsg"
60: .Ft "struct in6_addr *"
61: .Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index"
62: .Ft int
63: .Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index"
64: .\"
65: .Sh DESCRIPTION
66: RFC 2292 IPv6 advanced API defines eight
67: functions that the application calls to build and examine a Routing
68: header.
69: Four functions build a Routing header:
70: .Bl -hang
71: .It Fn inet6_rthdr_space
72: return #bytes required for ancillary data
73: .It Fn inet6_rthdr_init
74: initialize ancillary data for Routing header
75: .It Fn inet6_rthdr_add
1.3 ! wiz 76: add IPv6 address & flags to Routing header
1.1 christos 77: .It Fn inet6_rthdr_lasthop
78: specify the flags for the final hop
79: .El
80: .Pp
81: Four functions deal with a returned Routing header:
82: .Bl -hang
83: .It Fn inet6_rthdr_reverse
84: reverse a Routing header
85: .It Fn inet6_rthdr_segments
86: return #segments in a Routing header
87: .It Fn inet6_rthdr_getaddr
88: fetch one address from a Routing header
89: .It Fn inet6_rthdr_getflags
90: fetch one flag from a Routing header
91: .El
92: .Pp
93: The function prototypes for these functions are all in the
1.2 joerg 94: .In netinet/in.h
1.1 christos 95: header.
96: .\"
97: .Ss inet6_rthdr_space
98: This function returns the number of bytes required to hold a Routing
99: header of the specified
100: .Fa type
101: containing the specified number of
102: .Fa segments
103: .Pq addresses .
104: For an IPv6 Type 0 Routing header, the number
105: of segments must be between 1 and 23, inclusive.
106: The return value
107: includes the size of the cmsghdr structure that precedes the Routing
108: header, and any required padding.
109: .Pp
110: If the return value is 0, then either the type of the Routing header
111: is not supported by this implementation or the number of segments is
112: invalid for this type of Routing header.
113: .Pp
114: Note: This function returns the size but does not allocate the space
115: required for the ancillary data.
116: This allows an application to
117: allocate a larger buffer, if other ancillary data objects are
118: desired, since all the ancillary data objects must be specified to
119: .Xr sendmsg 2
120: as a single
121: .Li msg_control
122: buffer.
123: .\"
124: .Ss inet6_rthdr_init
125: This function initializes the buffer pointed to by
126: .Fa bp
127: to contain a
128: .Li cmsghdr
129: structure followed by a Routing header of the specified
130: .Fa type .
131: The
132: .Li cmsg_len
133: member of the
134: .Li cmsghdr
135: structure is initialized to the
136: size of the structure plus the amount of space required by the
137: Routing header.
138: The
139: .Li cmsg_level
140: and
141: .Li cmsg_type
142: members are also initialized as required.
143: .Pp
144: The caller must allocate the buffer and its size can be determined by
145: calling
146: .Fn inet6_rthdr_space .
147: .Pp
148: Upon success the return value is the pointer to the
149: .Li cmsghdr
150: structure, and this is then used as the first argument to the next
151: two functions.
152: Upon an error the return value is
153: .Dv NULL .
154: .\"
155: .Ss inet6_rthdr_add
156: This function adds the address pointed to by
157: .Fa addr
158: to the end of the
159: Routing header being constructed and sets the type of this hop to the
160: value of
161: .Fa flags .
162: For an IPv6 Type 0 Routing header,
163: .Fa flags
164: must be
165: either
166: .Dv IPV6_RTHDR_LOOSE
167: or
168: .Dv IPV6_RTHDR_STRICT .
169: .Pp
170: If successful, the
171: .Li cmsg_len
172: member of the
173: .Li cmsghdr
174: structure is
175: updated to account for the new address in the Routing header and the
176: return value of the function is 0.
177: Upon an error the return value of
178: the function is -1.
179: .\"
180: .Ss inet6_rthdr_lasthop
181: This function specifies the Strict/Loose flag for the final hop of a
182: Routing header.
183: For an IPv6 Type 0 Routing header,
184: .Fa flags
185: must be either
186: .Dv IPV6_RTHDR_LOOSE
187: or
188: .Dv IPV6_RTHDR_STRICT .
189: .Pp
190: The return value of the function is 0 upon success, or -1 upon an error.
191: .Pp
192: Notice that a Routing header specifying
193: .Li N
194: intermediate nodes requires
195: .Li N+1
196: Strict/Loose flags.
197: This requires
198: .Li N
199: calls to
200: .Fn inet6_rthdr_add
201: followed by one call to
202: .Fn inet6_rthdr_lasthop .
203: .\"
204: .Ss inet6_rthdr_reverse
205: This function takes a Routing header that was received as ancillary
206: data
207: .Po
208: pointed to by the first argument,
209: .Fa in
210: .Pc
211: and writes a new Routing
212: header that sends datagrams along the reverse of that route.
213: Both
214: arguments are allowed to point to the same buffer
215: .Pq that is, the reversal can occur in place .
216: .Pp
217: The return value of the function is 0 on success, or -1 upon an
218: error.
219: .\"
220: .Ss inet6_rthdr_segments
221: This function returns the number of segments
222: .Pq addresses
223: contained in
224: the Routing header described by
225: .Fa cmsg .
226: On success the return value is
227: between 1 and 23, inclusive.
228: The return value of the function is -1 upon an error.
229: .\"
230: .Ss inet6_rthdr_getaddr
231: This function returns a pointer to the IPv6 address specified by
232: .Fa index
233: .Po
234: which must have a value between 1 and the value returned by
235: .Fn inet6_rthdr_segments
236: .Pc
237: in the Routing header described by
238: .Fa cmsg .
239: An
240: application should first call
241: .Fn inet6_rthdr_segments
242: to obtain the number of segments in the Routing header.
243: .Pp
244: Upon an error the return value of the function is
245: .Dv NULL .
246: .\"
247: .Ss inet6_rthdr_getflags
248: This function returns the flags value specified by
249: .Fa index
250: .Po
251: which must
252: have a value between 0 and the value returned by
253: .Fn inet6_rthdr_segments
254: .Pc
255: in the Routing header described by
256: .Fa cmsg .
257: For an IPv6 Type 0 Routing header the return value will be either
258: .Dv IPV6_RTHDR_LOOSE
259: or
260: .Dv IPV6_RTHDR_STRICT .
261: .Pp
262: Upon an error the return value of the function is -1.
263: .Pp
264: Note: Addresses are indexed starting at 1, and flags starting at 0,
265: to maintain consistency with the terminology and figures in RFC 2460.
266: .\"
267: .Sh EXAMPLES
268: RFC 2292 gives comprehensive examples in chapter 8.
269: .\"
270: .Sh DIAGNOSTICS
271: .Fn inet6_rthdr_space
272: returns 0 on errors.
273: .Pp
274: .Fn inet6_rthdr_add ,
275: .Fn inet6_rthdr_lasthop
276: and
277: .Fn inet6_rthdr_reverse
278: return 0 on success, and returns -1 on error.
279: .Pp
280: .Fn inet6_rthdr_init
281: and
282: .Fn inet6_rthdr_getaddr
283: return
284: .Dv NULL
285: on error.
286: .Pp
287: .Fn inet6_rthdr_segments
288: and
289: .Fn inet6_rthdr_getflags
290: return -1 on error.
291: .\"
292: .Sh SEE ALSO
293: .Rs
294: .%A W. Stevens
295: .%A M. Thomas
296: .%T "Advanced Sockets API for IPv6"
297: .%N RFC 2292
298: .%D February 1998
299: .Re
300: .Rs
301: .%A S. Deering
302: .%A R. Hinden
303: .%T "Internet Protocol, Version 6 (IPv6) Specification"
304: .%N RFC 2460
305: .%D December 1998
306: .Re
307: .\"
308: .Sh STANDARDS
309: The functions
310: are documented in
311: .Dq Advanced Sockets API for IPv6
312: .Pq RFC 2292 .
313: .\"
314: .Sh HISTORY
315: The implementation first appeared in KAME advanced networking kit.
316: .\"
317: .Sh BUGS
318: The text was shamelessly copied from RFC 2292.
319: .Pp
320: .Fn inet6_rthdr_reverse
321: is not implemented yet.
CVSweb <webmaster@jp.NetBSD.org>