summaryrefslogtreecommitdiff
path: root/src/lib/libc
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc')
-rw-r--r--src/lib/libc/net/Makefile.inc8
-rw-r--r--src/lib/libc/net/gai_strerror.3118
-rw-r--r--src/lib/libc/net/getaddrinfo.3531
-rw-r--r--src/lib/libc/net/getnameinfo.3343
-rw-r--r--src/lib/libc/net/inet6_option_space.3444
-rw-r--r--src/lib/libc/net/inet6_rthdr_space.3317
6 files changed, 4 insertions, 1757 deletions
diff --git a/src/lib/libc/net/Makefile.inc b/src/lib/libc/net/Makefile.inc
index 79bfbb6b91..3d959d6be0 100644
--- a/src/lib/libc/net/Makefile.inc
+++ b/src/lib/libc/net/Makefile.inc
@@ -1,4 +1,4 @@
1# $OpenBSD: Makefile.inc,v 1.35 2004/12/06 10:46:35 jmc Exp $ 1# $OpenBSD: Makefile.inc,v 1.36 2004/12/20 03:26:43 itojun Exp $
2 2
3# net sources 3# net sources
4.PATH: ${LIBCSRCDIR}/arch/${MACHINE_ARCH}/net ${LIBCSRCDIR}/net 4.PATH: ${LIBCSRCDIR}/arch/${MACHINE_ARCH}/net ${LIBCSRCDIR}/net
@@ -28,10 +28,10 @@ SRCS+= ip6opt.c rthdr.c vars6.c
28 28
29.include "${LIBCSRCDIR}/arch/${MACHINE_ARCH}/net/Makefile.inc" 29.include "${LIBCSRCDIR}/arch/${MACHINE_ARCH}/net/Makefile.inc"
30 30
31MAN+= byteorder.3 ethers.3 gai_strerror.3 getaddrinfo.3 gethostbyname.3 \ 31MAN+= byteorder.3 ethers.3 gethostbyname.3 \
32 getifaddrs.3 getnameinfo.3 getnetent.3 getprotoent.3 \ 32 getifaddrs.3 getnetent.3 getprotoent.3 \
33 getrrsetbyname.3 getservent.3 if_indextoname.3 inet.3 \ 33 getrrsetbyname.3 getservent.3 if_indextoname.3 inet.3 \
34 inet_net.3 inet6_option_space.3 inet6_rthdr_space.3 \ 34 inet_net.3 \
35 ipx.3 link_addr.3 net_addrcmp.3 ns.3 \ 35 ipx.3 link_addr.3 net_addrcmp.3 ns.3 \
36 rcmd.3 rcmdsh.3 resolver.3 36 rcmd.3 rcmdsh.3 resolver.3
37 37
diff --git a/src/lib/libc/net/gai_strerror.3 b/src/lib/libc/net/gai_strerror.3
deleted file mode 100644
index 75eb1517f4..0000000000
--- a/src/lib/libc/net/gai_strerror.3
+++ /dev/null
@@ -1,118 +0,0 @@
1.\" $OpenBSD: gai_strerror.3,v 1.1 2004/12/06 10:46:35 jmc Exp $
2.\"
3.\" Copyright (c) 1983, 1987, 1991, 1993
4.\" The Regents of the University of California. 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 University 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 REGENTS 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 REGENTS 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.Dd December 3, 2004
31.Dt GAI_STRERROR 3
32.Os
33.\"
34.Sh NAME
35.Nm gai_strerror
36.Nd return EAI_xxx error message
37.\"
38.Sh SYNOPSIS
39.Fd #include <sys/types.h>
40.Fd #include <sys/socket.h>
41.Fd #include <netdb.h>
42.Ft "char *"
43.Fn gai_strerror "int ecode"
44.\"
45.Sh DESCRIPTION
46To aid applications in printing error messages based on the
47.Dv EAI_xxx
48codes returned by
49.Xr getaddrinfo 3
50and
51.Xr getnameinfo 3 ,
52.Fn gai_strerror
53is defined.
54The argument is one of the
55.Dv EAI_xxx
56values detailed below
57and the return value points to a string describing the error.
58If the argument is not one of the
59.Dv EAI_xxx
60values,
61the function still returns a pointer to a string whose contents
62indicate an unknown error.
63.Pp
64The error return status from
65.Xr getaddrinfo 3
66and
67.Xr getnameinfo 3
68is zero on success and non-zero on errors.
69Non-zero error codes are defined in
70.Aq Pa netdb.h ,
71and are as follows:
72.Pp
73.Bl -tag -width "EAI_ADDRFAMILYXX" -offset indent -compact
74.It Dv EAI_ADDRFAMILY
75Address family for
76.Fa nodename
77not supported.
78.It Dv EAI_AGAIN
79Temporary failure in name resolution.
80.It Dv EAI_BADFLAGS
81Invalid value for
82.Fa ai_flags .
83.It Dv EAI_BADHINTS
84Invalid value for hints.
85.It Dv EAI_FAIL
86Non-recoverable failure in name resolution.
87.It Dv EAI_FAMILY
88.Fa ai_family
89not supported.
90.It Dv EAI_MEMORY
91Memory allocation failure.
92.It Dv EAI_NODATA
93No address associated with
94.Fa nodename .
95.It Dv EAI_NONAME
96.Fa nodename
97nor
98.Fa servname
99provided, or not known.
100.It Dv EAI_PROTOCOL
101Resolved protocol is unknown.
102.It Dv EAI_SERVICE
103.Fa servname
104not supported for
105.Fa ai_socktype .
106.It Dv EAI_SOCKTYPE
107.Fa ai_socktype
108not supported.
109.It Dv EAI_SYSTEM
110System error returned in
111.Va errno .
112.El
113.\"
114.Sh SEE ALSO
115.Xr getaddrinfo 3 ,
116.Xr getnameinfo 3
117.Sh HISTORY
118The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
diff --git a/src/lib/libc/net/getaddrinfo.3 b/src/lib/libc/net/getaddrinfo.3
deleted file mode 100644
index e74fdf6ed7..0000000000
--- a/src/lib/libc/net/getaddrinfo.3
+++ /dev/null
@@ -1,531 +0,0 @@
1.\" $OpenBSD: getaddrinfo.3,v 1.29 2004/12/06 10:46:35 jmc Exp $
2.\" $KAME: getaddrinfo.3,v 1.29 2001/02/12 09:24:45 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.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
32.\"
33.Dd May 25, 1995
34.Dt GETADDRINFO 3
35.Os
36.\"
37.Sh NAME
38.Nm getaddrinfo ,
39.Nm freeaddrinfo
40.Nd nodename-to-address translation in protocol-independent manner
41.\"
42.Sh SYNOPSIS
43.Fd #include <sys/types.h>
44.Fd #include <sys/socket.h>
45.Fd #include <netdb.h>
46.Ft int
47.Fn getaddrinfo "const char *nodename" "const char *servname" \
48"const struct addrinfo *hints" "struct addrinfo **res"
49.Ft void
50.Fn freeaddrinfo "struct addrinfo *ai"
51.\"
52.Sh DESCRIPTION
53The
54.Fn getaddrinfo
55function is defined for protocol-independent nodename-to-address translation.
56It performs the functionality of
57.Xr gethostbyname 3
58and
59.Xr getservbyname 3 ,
60but in a more sophisticated manner.
61.Pp
62All of the information returned by
63.Fn getaddrinfo
64is dynamically allocated:
65the
66.Li addrinfo
67structures, the socket address structures, and canonical node name
68strings pointed to by the addrinfo structures.
69To return this information to the system the function
70.Fn freeaddrinfo
71is called.
72The
73.Fa addrinfo
74structure pointed to by the
75.Fa ai
76argument is freed,
77along with any dynamic storage pointed to by the structure.
78This operation is repeated until a
79.Dv NULL
80.Fa ai_next
81pointer is encountered.
82.Pp
83To aid applications in printing error messages based on the
84.Dv EAI_xxx
85codes returned by
86.Fn getaddrinfo ,
87.Fn gai_strerror
88is defined.
89See
90.Xr gai_strerror 3
91for more information.
92.Pp
93The implementation allows experimental numeric IPv6 address notation with
94scope identifier.
95By appending the percent character and scope identifier to addresses,
96you can fill the
97.Li sin6_scope_id
98field for addresses.
99This would make management of scoped address easier,
100and allows cut-and-paste input of scoped address.
101.Pp
102At this moment the code supports only link-local addresses with the format.
103Scope identifier is hardcoded to the name of the hardware interface associated
104with the link
105.Po
106such as
107.Li ne0
108.Pc .
109An example is
110.Dq Li fe80::1%ne0 ,
111which means
112.Do
113.Li fe80::1
114on the link associated with the
115.Li ne0
116interface
117.Dc .
118.Pp
119The IPv6 implementation is still very experimental and non-standard.
120The current implementation assumes a one-to-one relationship between
121the interface and link, which is not necessarily true from the specification.
122.Pp
123The
124.Li addrinfo
125structure is defined as a result of including the
126.Aq Pa netdb.h
127header:
128.Bd -literal
129struct addrinfo {
130 int ai_flags; /* input flags */
131 int ai_family; /* protocol family for socket */
132 int ai_socktype; /* socket type */
133 int ai_protocol; /* protocol for socket */
134 socklen_t ai_addrlen; /* length of socket-address */
135 struct sockaddr *ai_addr; /* socket-address for socket */
136 char *ai_canonname; /* canonical name for service location */
137 struct addrinfo *ai_next; /* pointer to next in list */
138};
139.Ed
140.Pp
141The
142.Fa nodename
143and
144.Fa servname
145arguments are pointers to NUL-terminated strings or
146.Dv NULL .
147One or both of these two arguments must be a non-null pointer.
148In the normal client scenario, both the
149.Fa nodename
150and
151.Fa servname
152are specified.
153In the normal server scenario, only the
154.Fa servname
155is specified.
156A non-null
157.Fa nodename
158string can be either a node name or a numeric host address string
159(i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
160A non-null
161.Fa servname
162string can be either a service name or a decimal port number.
163.Pp
164The caller can optionally pass an
165.Li addrinfo
166structure, pointed to by the third argument,
167to provide hints concerning the type of socket that the caller supports.
168In this
169.Fa hints
170structure all members other than
171.Fa ai_flags ,
172.Fa ai_family ,
173.Fa ai_socktype ,
174and
175.Fa ai_protocol
176must be zero or a null pointer.
177A value of
178.Dv PF_UNSPEC
179for
180.Fa ai_family
181means the caller will accept any protocol family.
182A value of 0 for
183.Fa ai_socktype
184means the caller will accept any socket type.
185A value of 0 for
186.Fa ai_protocol
187means the caller will accept any protocol.
188For example, if the caller handles only TCP and not UDP, then the
189.Fa ai_socktype
190member of the hints structure should be set to
191.Dv SOCK_STREAM
192when
193.Fn getaddrinfo
194is called.
195If the caller handles only IPv4 and not IPv6, then the
196.Fa ai_family
197member of the
198.Fa hints
199structure should be set to
200.Dv PF_INET
201when
202.Fn getaddrinfo
203is called.
204If the third argument to
205.Fn getaddrinfo
206is a null pointer, this is the same as if the caller had filled in an
207.Li addrinfo
208structure initialized to zero with
209.Fa ai_family
210set to
211.Dv PF_UNSPEC .
212.Pp
213Upon successful return a pointer to a linked list of one or more
214.Li addrinfo
215structures is returned through the final argument.
216The caller can process each
217.Li addrinfo
218structure in this list by following the
219.Fa ai_next
220pointer, until a null pointer is encountered.
221In each returned
222.Li addrinfo
223structure the three members
224.Fa ai_family ,
225.Fa ai_socktype ,
226and
227.Fa ai_protocol
228are the corresponding arguments for a call to the
229.Xr socket 2
230function.
231In each
232.Li addrinfo
233structure the
234.Fa ai_addr
235member points to a filled-in socket address structure whose length is
236specified by the
237.Fa ai_addrlen
238member.
239.Pp
240The
241.Fa ai_flags
242argument can be set to any of the following values, OR'd together:
243.Bl -tag -width "AI_NUMERICHOSTXX"
244.It AI_PASSIVE
245If the
246.Dv AI_PASSIVE
247bit is set,
248the caller plans to use the returned socket address
249structure in a call to
250.Xr bind 2 .
251In this case, if the
252.Fa nodename
253argument is a null pointer, then the IP address portion of the socket
254address structure will be set to
255.Dv INADDR_ANY
256for an IPv4 address or
257.Dv IN6ADDR_ANY_INIT
258for an IPv6 address.
259.Pp
260If the
261.Dv AI_PASSIVE
262bit is not set,
263the returned socket address structure will be ready for a
264call to
265.Xr connect 2
266.Pq for a connection-oriented protocol
267or either
268.Xr connect 2 ,
269.Xr sendto 2 ,
270or
271.Xr sendmsg 2
272.Pq for a connectionless protocol .
273In this case, if the
274.Fa nodename
275argument is a null pointer, then the IP address portion of the
276socket address structure will be set to the loopback address.
277.It AI_CANONNAME
278If the
279.Dv AI_CANONNAME
280bit is set,
281then upon successful return the
282.Fa ai_canonname
283member of the first
284.Li addrinfo
285structure in the linked list will point to a NUL-terminated string
286containing the canonical name of the specified
287.Fa nodename .
288.It AI_NUMERICHOST
289If the
290.Dv AI_NUMERICHOST
291bit is set,
292then a non-null
293.Fa nodename
294string must be a numeric host address string.
295Otherwise an error of
296.Dv EAI_NONAME
297is returned.
298This flag prevents any type of name resolution service,
299such as DNS,
300from being called.
301.It AI_NUMERICSERV
302If the
303.Dv AI_NUMERICSERV
304bit is set,
305then a non-null
306.Fa servname
307string must be a numeric port string.
308Otherwise an error of
309.Dv EAI_NONAME
310is returned.
311This flag prevents any type of name resolution service,
312such as NIS,
313from being called.
314.El
315.Pp
316The arguments to
317.Fn getaddrinfo
318must be sufficiently consistent and unambiguous.
319Issues to watch out for are:
320.Bl -bullet
321.It
322.Fn getaddrinfo
323will raise an error if members of the
324.Fa hints
325structure are not consistent.
326For example, for internet address families,
327.Fn getaddrinfo
328will raise an error if you specify
329.Dv SOCK_STREAM
330to
331.Fa ai_socktype
332while you specify
333.Dv IPPROTO_UDP
334to
335.Fa ai_protocol .
336.It
337If you specify a
338.Fa servname
339which is defined only for certain
340.Fa ai_socktype ,
341.Fn getaddrinfo
342will raise an error because the arguments are not consistent.
343For example,
344.Fn getaddrinfo
345will raise an error if you ask for
346.Dq Li tftp
347service on
348.Dv SOCK_STREAM .
349.It
350For internet address families, if you specify
351.Fa servname
352while you set
353.Fa ai_socktype
354to
355.Dv SOCK_RAW ,
356.Fn getaddrinfo
357will raise an error, because service names are not defined for the internet
358.Dv SOCK_RAW
359space.
360.It
361If you specify a numeric
362.Fa servname ,
363while leaving
364.Fa ai_socktype
365and
366.Fa ai_protocol
367unspecified,
368.Fn getaddrinfo
369will raise an error.
370This is because the numeric
371.Fa servname
372does not identify any socket type, and
373.Fn getaddrinfo
374is not allowed to glob the argument in such case.
375.El
376.\"
377.Sh RETURN VALUES
378.Fn getaddrinfo
379returns zero on success, and non-zero on errors.
380See
381.Xr gai_strerror 3
382for a description of the non-zero error codes.
383.\"
384.Sh EXAMPLES
385The following code tries to connect to
386.Dq Li www.kame.net
387service
388.Dq Li http .
389via stream socket.
390It loops through all the addresses available, regardless of address family.
391If the destination resolves to an IPv4 address, it will use
392.Dv AF_INET
393socket.
394Similarly, if it resolves to IPv6,
395.Dv AF_INET6
396socket is used.
397Observe that there is no hardcoded reference to a particular address family.
398The code works even if
399.Nm getaddrinfo
400returns addresses that are not IPv4/v6.
401.Bd -literal -offset indent
402struct addrinfo hints, *res, *res0;
403int error;
404int s;
405const char *cause = NULL;
406
407memset(&hints, 0, sizeof(hints));
408hints.ai_family = PF_UNSPEC;
409hints.ai_socktype = SOCK_STREAM;
410error = getaddrinfo("www.kame.net", "http", &hints, &res0);
411if (error) {
412 errx(1, "%s", gai_strerror(error));
413 /*NOTREACHED*/
414}
415s = -1;
416for (res = res0; res; res = res->ai_next) {
417 s = socket(res->ai_family, res->ai_socktype,
418 res->ai_protocol);
419 if (s < 0) {
420 cause = "socket";
421 continue;
422 }
423
424 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
425 cause = "connect";
426 close(s);
427 s = -1;
428 continue;
429 }
430
431 break; /* okay we got one */
432}
433if (s < 0) {
434 err(1, "%s", cause);
435 /*NOTREACHED*/
436}
437freeaddrinfo(res0);
438.Ed
439.Pp
440The following example tries to open a wildcard listening socket onto service
441.Dq Li http ,
442for all the address families available.
443.Bd -literal -offset indent
444struct addrinfo hints, *res, *res0;
445int error;
446int s[MAXSOCK];
447int nsock;
448const char *cause = NULL;
449
450memset(&hints, 0, sizeof(hints));
451hints.ai_family = PF_UNSPEC;
452hints.ai_socktype = SOCK_STREAM;
453hints.ai_flags = AI_PASSIVE;
454error = getaddrinfo(NULL, "http", &hints, &res0);
455if (error) {
456 errx(1, "%s", gai_strerror(error));
457 /*NOTREACHED*/
458}
459nsock = 0;
460for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
461 s[nsock] = socket(res->ai_family, res->ai_socktype,
462 res->ai_protocol);
463 if (s[nsock] < 0) {
464 cause = "socket";
465 continue;
466 }
467
468 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
469 cause = "bind";
470 close(s[nsock]);
471 continue;
472 }
473 (void) listen(s[nsock], 5);
474
475 nsock++;
476}
477if (nsock == 0) {
478 err(1, "%s", cause);
479 /*NOTREACHED*/
480}
481freeaddrinfo(res0);
482.Ed
483.\"
484.Sh SEE ALSO
485.Xr gai_strerror 3 ,
486.Xr gethostbyname 3 ,
487.Xr getnameinfo 3 ,
488.Xr getservbyname 3 ,
489.Xr hosts 5 ,
490.Xr resolv.conf 5 ,
491.Xr services 5 ,
492.Xr hostname 7 ,
493.Xr named 8
494.Rs
495.%A R. Gilligan
496.%A S. Thomson
497.%A J. Bound
498.%A J. McCann
499.%A W. Stevens
500.%T Basic Socket Interface Extensions for IPv6
501.%R RFC 3493
502.%D February 2003
503.Re
504.Rs
505.%A Tatsuya Jinmei
506.%A Atsushi Onoe
507.%T "An Extension of Format for IPv6 Scoped Addresses"
508.%R internet draft
509.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
510.%O work in progress material
511.Re
512.Rs
513.%A Craig Metz
514.%T Protocol Independence Using the Sockets API
515.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
516.%D June 2000
517.Re
518.\"
519.Sh STANDARDS
520The
521.Fn getaddrinfo
522function is defined in IEEE POSIX 1003.1g draft specification,
523and documented in
524.Dq Basic Socket Interface Extensions for IPv6
525.Pq RFC 3493 .
526.\"
527.Sh HISTORY
528The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
529.\"
530.Sh BUGS
531The current implementation is not thread-safe.
diff --git a/src/lib/libc/net/getnameinfo.3 b/src/lib/libc/net/getnameinfo.3
deleted file mode 100644
index c01646c8a7..0000000000
--- a/src/lib/libc/net/getnameinfo.3
+++ /dev/null
@@ -1,343 +0,0 @@
1.\" $OpenBSD: getnameinfo.3,v 1.28 2004/12/06 10:46:35 jmc Exp $
2.\" $KAME: getnameinfo.3,v 1.20 2001/01/05 13:37:37 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.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
32.\"
33.Dd May 25, 1995
34.Dt GETNAMEINFO 3
35.Os
36.\"
37.Sh NAME
38.Nm getnameinfo
39.Nd address-to-nodename translation in protocol-independent manner
40.\"
41.Sh SYNOPSIS
42.Fd #include <sys/types.h>
43.Fd #include <sys/socket.h>
44.Fd #include <netdb.h>
45.Ft int
46.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \
47"char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags"
48.\"
49.Sh DESCRIPTION
50The
51.Fn getnameinfo
52function is defined for protocol-independent address-to-nodename translation.
53Its functionality is a reverse conversion of
54.Xr getaddrinfo 3 ,
55and implements similar functionality to
56.Xr gethostbyaddr 3
57and
58.Xr getservbyport 3
59in a more sophisticated manner.
60.Pp
61This function looks up an IP address and port number provided by the
62caller in the DNS and system-specific database, and returns text
63strings for both in buffers provided by the caller.
64The function indicates successful completion by a zero return value;
65a non-zero return value indicates failure.
66.Pp
67To aid applications in printing error messages based on the
68.Dv EAI_xxx
69codes returned by
70.Fn getnameinfo ,
71.Fn gai_strerror
72is defined.
73See
74.Xr gai_strerror 3
75for more information.
76.Pp
77The implementation allows experimental numeric IPv6 address notation with
78scope identifier.
79IPv6 link-local address will appear as a string like
80.Dq Li fe80::1%ne0 .
81Refer to
82.Xr getaddrinfo 3
83for the notation.
84.Pp
85The first argument,
86.Fa sa ,
87points to either a
88.Li sockaddr_in
89structure (for IPv4) or a
90.Li sockaddr_in6
91structure (for IPv6) that holds the IP address and port number.
92The
93.Fa salen
94argument gives the length of the
95.Li sockaddr_in
96or
97.Li sockaddr_in6
98structure.
99.Pp
100The function returns the nodename associated with the IP address in
101the buffer pointed to by the
102.Fa host
103argument.
104The caller provides the size of this buffer via the
105.Fa hostlen
106argument.
107The service name associated with the port number is returned in the buffer
108pointed to by
109.Fa serv ,
110and the
111.Fa servlen
112argument gives the length of this buffer.
113The caller specifies not to return either string by providing a zero
114value for the
115.Fa hostlen
116or
117.Fa servlen
118arguments.
119Otherwise, the caller must provide buffers large enough to hold the
120nodename and the service name, including the terminating null characters.
121.Pp
122Unfortunately most systems do not provide constants that specify the
123maximum size of either a fully-qualified domain name or a service name.
124Therefore to aid the application in allocating buffers for these two
125returned strings the following constants are defined in
126.Aq Pa netdb.h :
127.Bd -literal -offset indent
128#define NI_MAXHOST MAXHOSTNAMELEN
129#define NI_MAXSERV 32
130.Ed
131.Pp
132The first value is actually defined as the constant
133.Dv MAXDNAME
134in recent versions of BIND's
135.Aq Pa arpa/nameser.h
136header (older versions of BIND define this constant to be 256)
137and the second is a guess based on the services listed in the current
138Assigned Numbers RFC.
139.Pp
140The final argument is a
141.Fa flag
142that changes the default actions of this function.
143The flags are defined in
144.Aq Pa netdb.h
145and are as follows:
146.Bl -tag -width "NI_NUMERICHOSTXX"
147.It Dv NI_NOFQDN
148By default the fully-qualified domain name (FQDN) for the host is
149looked up using DNS and returned.
150If the flag bit
151.Dv NI_NOFQDN
152is set, only the nodename portion of the FQDN is returned for local hosts.
153.It Dv NI_NUMERICHOST
154If the
155.Fa flag
156bit
157.Dv NI_NUMERICHOST
158is set, or if the host's name cannot be located using DNS,
159the numeric form of the host's address is returned instead of its name
160.Po
161e.g., by calling
162.Xr inet_ntop 3
163instead of
164.Xr gethostbyaddr 3
165.Pc .
166The two
167.Dv NI_NUMERICxxx
168flags are required to support the
169.Fl n
170flag that many commands provide.
171.It Dv NI_NAMEREQD
172If the
173.Fa flag
174bit
175.Dv NI_NAMEREQD
176is set, an error is returned if the host's name cannot be located using DNS.
177.It Dv NI_NUMERICSERV
178If the flag bit
179.Dv NI_NUMERICSERV
180is set, the numeric form of the service address is returned
181.Pq e.g., its port number
182instead of its name.
183The two
184.Dv NI_NUMERICxxx
185flags are required to support the
186.Fl n
187flag that many commands provide.
188.It Dv NI_DGRAM
189A fifth flag bit,
190.Dv NI_DGRAM ,
191specifies that the service is a datagram service, and causes
192.Xr getservbyport 3
193to be called with a second argument of
194.Qq udp
195instead of its default of
196.Qq tcp .
197This is required for the few ports (512-514)
198that have different services for UDP and TCP.
199.El
200.\"
201.Sh RETURN VALUES
202.Fn getnameinfo
203returns zero on success, and non-zero on errors.
204See
205.Xr gai_strerror 3
206for a description of the non-zero error codes.
207.\"
208.Sh EXAMPLES
209The following code tries to get a numeric hostname, and service name,
210for a given socket address.
211Observe that there is no hardcoded reference to a particular address family.
212.Bd -literal -offset indent
213struct sockaddr *sa; /* input */
214char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
215
216if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
217 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
218 errx(1, "could not get numeric hostname");
219 /*NOTREACHED*/
220}
221printf("host=%s, serv=%s\en", hbuf, sbuf);
222.Ed
223.Pp
224The following version checks if the socket address has reverse address mapping:
225.Bd -literal -offset indent
226struct sockaddr *sa; /* input */
227char hbuf[NI_MAXHOST];
228
229if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
230 NI_NAMEREQD)) {
231 errx(1, "could not resolve hostname");
232 /*NOTREACHED*/
233}
234printf("host=%s\en", hbuf);
235.Ed
236.\"
237.Sh SEE ALSO
238.Xr gai_strerror 3 ,
239.Xr getaddrinfo 3 ,
240.Xr gethostbyaddr 3 ,
241.Xr getservbyport 3 ,
242.Xr hosts 5 ,
243.Xr resolv.conf 5 ,
244.Xr services 5 ,
245.Xr hostname 7 ,
246.Xr named 8
247.Rs
248.%A R. Gilligan
249.%A S. Thomson
250.%A J. Bound
251.%A W. Stevens
252.%T Basic Socket Interface Extensions for IPv6
253.%R RFC 2553
254.%D March 1999
255.Re
256.Rs
257.%A Tatsuya Jinmei
258.%A Atsushi Onoe
259.%T "An Extension of Format for IPv6 Scoped Addresses"
260.%R internet draft
261.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
262.%O work in progress material
263.Re
264.Rs
265.%A Craig Metz
266.%T Protocol Independence Using the Sockets API
267.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
268.%D June 2000
269.Re
270.\"
271.Sh STANDARDS
272The
273.Fn getnameinfo
274function is defined in IEEE POSIX 1003.1g draft specification,
275and documented in
276.Dq Basic Socket Interface Extensions for IPv6
277.Pq RFC 2553 .
278.\"
279.Sh HISTORY
280The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
281.\"
282.Sh CAVEATS
283.Fn getnameinfo
284returns both numeric and FQDN notation of the address specified in
285.Fa sa .
286There is no return value that indicates if the string returned in
287.Fa host
288is a result of binary to numeric-text translation (like
289.Xr inet_ntop 3 ) ,
290or the result of DNS reverse lookup.
291Therefore, malicious parties could set up a PTR record as below:
292.Bd -literal -offset indent
2931.0.0.127.in-addr.arpa. IN PTR 10.1.1.1
294.Ed
295.Pp
296and trick the caller of
297.Fn getnameinfo
298into believing that
299.Fa sa
300is
301.Li 10.1.1.1
302when it actually is
303.Li 127.0.0.1 .
304.Pp
305To prevent such attacks, the use of
306.Dv NI_NAMEREQD
307is recommended when you use the result of
308.Fn getnameinfo
309for access control purposes:
310.Bd -literal -offset indent
311struct sockaddr *sa;
312socklen_t salen;
313char addr[NI_MAXHOST];
314struct addrinfo hints, *res;
315int error;
316
317error = getnameinfo(sa, salen, addr, sizeof(addr),
318 NULL, 0, NI_NAMEREQD);
319if (error == 0) {
320 memset(&hints, 0, sizeof(hints));
321 hints.ai_socktype = SOCK_DGRAM; /*dummy*/
322 hints.ai_flags = AI_NUMERICHOST;
323 if (getaddrinfo(addr, "0", &hints, &res) == 0) {
324 /* malicious PTR record */
325 freeaddrinfo(res);
326 printf("bogus PTR record\\n");
327 return -1;
328 }
329 /* addr is FQDN as a result of PTR lookup */
330} else {
331 /* addr is numeric string */
332 error = getnameinfo(sa, salen, addr, sizeof(addr),
333 NULL, 0, NI_NUMERICHOST);
334}
335.Ed
336.\"
337.Sh BUGS
338The current implementation is not thread-safe.
339.Pp
340.Ox
341intentionally uses a different
342.Dv NI_MAXHOST
343value from what RFC 2553 suggests, to avoid buffer length handling mistakes.
diff --git a/src/lib/libc/net/inet6_option_space.3 b/src/lib/libc/net/inet6_option_space.3
deleted file mode 100644
index 4e5dc22711..0000000000
--- a/src/lib/libc/net/inet6_option_space.3
+++ /dev/null
@@ -1,444 +0,0 @@
1.\" $OpenBSD: inet6_option_space.3,v 1.13 2003/08/08 09:26:02 jmc Exp $
2.\" $KAME: inet6_option_space.3,v 1.7 2000/05/17 14:32:13 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_OPTION_SPACE 3
33.Os
34.\"
35.Sh NAME
36.Nm inet6_option_space ,
37.Nm inet6_option_init ,
38.Nm inet6_option_append ,
39.Nm inet6_option_alloc ,
40.Nm inet6_option_next ,
41.Nm inet6_option_find
42.Nd IPv6 Hop-by-Hop and Destination Options manipulation
43.\"
44.Sh SYNOPSIS
45.Fd #include <netinet/in.h>
46.Ft "int"
47.Fn inet6_option_space "int nbytes"
48.Ft "int"
49.Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
50.Ft "int"
51.Fn inet6_option_append "struct cmsghdr *cmsg" "const u_int8_t *typep" "int multx" "int plusy"
52.Ft "u_int8_t *"
53.Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy"
54.Ft "int"
55.Fn inet6_option_next "const struct cmsghdr *cmsg" "u_int8_t **tptrp"
56.Ft "int"
57.Fn inet6_option_find "const struct cmsghdr *cmsg" "u_int8_t **tptrp" "int type"
58.\"
59.Sh DESCRIPTION
60.\"
61Building and parsing the Hop-by-Hop and Destination options is
62complicated due to alignment constraints, padding and
63ancillary data manipulation.
64RFC 2292 defines a set of functions to help the application.
65The function prototypes for
66these functions are all in the
67.Aq Pa netinet/in.h
68header.
69.\"
70.Ss inet6_option_space
71.Fn inet6_option_space
72returns the number of bytes required to hold an option when it is stored as
73ancillary data, including the
74.Li cmsghdr
75structure at the beginning,
76and any padding at the end
77.Po
78to make its size a multiple of 8 bytes
79.Pc .
80The argument is the size of the structure defining the option,
81which must include any pad bytes at the beginning
82.Po
83the value
84.Li y
85in the alignment term
86.Dq Li xn + y
87.Pc ,
88the type byte, the length byte, and the option data.
89.Pp
90Note: If multiple options are stored in a single ancillary data
91object, which is the recommended technique, this function
92overestimates the amount of space required by the size of
93.Li N-1
94.Li cmsghdr
95structures,
96where
97.Li N
98is the number of options to be stored in the object.
99This is of little consequence, since it is assumed that most
100Hop-by-Hop option headers and Destination option headers carry only
101one option
102.Pq appendix B of [RFC 2460] .
103.\"
104.Ss inet6_option_init
105.Fn inet6_option_init
106is called once per ancillary data object that will
107contain either Hop-by-Hop or Destination options.
108It returns
109.Li 0
110on success or
111.Li -1
112on an error.
113.Pp
114.Fa bp
115is a pointer to previously allocated space that will contain the
116ancillary data object.
117It must be large enough to contain all the
118individual options to be added by later calls to
119.Fn inet6_option_append
120and
121.Fn inet6_option_alloc .
122.Pp
123.Fa cmsgp
124is a pointer to a pointer to a
125.Li cmsghdr
126structure.
127.Fa *cmsgp
128is initialized by this function to point to the
129.Li cmsghdr
130structure constructed by this function in the buffer pointed to by
131.Fa bp .
132.Pp
133.Fa type
134is either
135.Dv IPV6_HOPOPTS
136or
137.Dv IPV6_DSTOPTS .
138This
139.Fa type
140is stored in the
141.Li cmsg_type
142member of the
143.Li cmsghdr
144structure pointed to by
145.Fa *cmsgp .
146.\"
147.Ss inet6_option_append
148This function appends a Hop-by-Hop option or a Destination option
149into an ancillary data object that has been initialized by
150.Fn inet6_option_init .
151This function returns
152.Li 0
153if it succeeds or
154.Li -1
155on an error.
156.Pp
157.Fa cmsg
158is a pointer to the
159.Li cmsghdr
160structure that must have been
161initialized by
162.Fn inet6_option_init .
163.Pp
164.Fa typep
165is a pointer to the 8-bit option type.
166It is assumed that this
167field is immediately followed by the 8-bit option data length field,
168which is then followed immediately by the option data.
169The caller
170initializes these three fields
171.Pq the type-length-value, or TLV
172before calling this function.
173.Pp
174The option type must have a value from
175.Li 2
176to
177.Li 255 ,
178inclusive.
179.Po
180.Li 0
181and
182.Li 1
183are reserved for the
184.Li Pad1
185and
186.Li PadN
187options, respectively.
188.Pc
189.Pp
190The option data length must have a value between
191.Li 0
192and
193.Li 255 ,
194inclusive, and is the length of the option data that follows.
195.Pp
196.Fa multx
197is the value
198.Li x
199in the alignment term
200.Dq Li xn + y .
201It must have a value of
202.Li 1 ,
203.Li 2 ,
204.Li 4 ,
205or
206.Li 8 .
207.Pp
208.Fa plusy
209is the value
210.Li y
211in the alignment term
212.Dq Li xn + y .
213It must have a value between
214.Li 0
215and
216.Li 7 ,
217inclusive.
218.\"
219.Ss inet6_option_alloc
220This function appends a Hop-by-Hop option or a Destination option
221into an ancillary data object that has been initialized by
222.Fn inet6_option_init .
223This function returns a pointer to the 8-bit
224option type field that starts the option on success, or
225.Dv NULL
226on an error.
227.Pp
228The difference between this function and
229.Fn inet6_option_append
230is that the latter copies the contents of a previously built option into
231the ancillary data object while the current function returns a
232pointer to the space in the data object where the option's TLV must
233then be built by the caller.
234.Pp
235.Fa cmsg
236is a pointer to the
237.Li cmsghdr
238structure that must have been
239initialized by
240.Fn inet6_option_init .
241.Pp
242.Fa datalen
243is the value of the option data length byte for this option.
244This value is required as an argument to allow the function to
245determine if padding must be appended at the end of the option.
246(The
247.Fn inet6_option_append
248function does not need a data length argument
249since the option data length must already be stored by the caller.)
250.Pp
251.Fa multx
252is the value
253.Li x
254in the alignment term
255.Dq Li xn + y .
256It must have a value of
257.Li 1 ,
258.Li 2 ,
259.Li 4 ,
260or
261.Li 8 .
262.Pp
263.Fa plusy
264is the value
265.Li y
266in the alignment term
267.Dq Li xn + y .
268It must have a value between
269.Li 0
270and
271.Li 7 ,
272inclusive.
273.\"
274.Ss inet6_option_next
275This function processes the next Hop-by-Hop option or Destination
276option in an ancillary data object.
277If another option remains to be
278processed, the return value of the function is
279.Li 0
280and
281.Fa *tptrp
282points to
283the 8-bit option type field
284(which is followed by the 8-bit option
285data length, followed by the option data).
286If no more options remain
287to be processed, the return value is
288.Li -1
289and
290.Fa *tptrp
291is
292.Dv NULL .
293If an error occurs, the return value is
294.Li -1
295and
296.Fa *tptrp
297is not
298.Dv NULL .
299.Pp
300.Fa cmsg
301is a pointer to
302.Li cmsghdr
303structure of which
304.Li cmsg_level
305equals
306.Dv IPPROTO_IPV6
307and
308.Li cmsg_type
309equals either
310.Dv IPV6_HOPOPTS
311or
312.Dv IPV6_DSTOPTS .
313.Pp
314.Fa tptrp
315is a pointer to a pointer to an 8-bit byte and
316.Fa *tptrp
317is used
318by the function to remember its place in the ancillary data object
319each time the function is called.
320The first time this function is
321called for a given ancillary data object,
322.Fa *tptrp
323must be set to
324.Dv NULL .
325.Pp
326Each time this function returns success,
327.Fa *tptrp
328points to the 8-bit
329option type field for the next option to be processed.
330.\"
331.Ss inet6_option_find
332This function is similar to the previously described
333.Fn inet6_option_next
334function, except this function lets the caller
335specify the option type to be searched for, instead of always
336returning the next option in the ancillary data object.
337.Fa cmsg
338is a
339pointer to
340.Li cmsghdr
341structure of which
342.Li cmsg_level
343equals
344.Dv IPPROTO_IPV6
345and
346.Li cmsg_type
347equals either
348.Dv IPV6_HOPOPTS
349or
350.Dv IPV6_DSTOPTS .
351.Pp
352.Fa tptrp
353is a pointer to a pointer to an 8-bit byte and
354.Fa *tptrp
355is used
356by the function to remember its place in the ancillary data object
357each time the function is called.
358The first time this function is
359called for a given ancillary data object,
360.Fa *tptrp
361must be set to
362.Dv NULL .
363.Pp
364This function starts searching for an option of the specified type
365beginning after the value of
366.Fa *tptrp .
367If an option of the specified
368type is located, this function returns
369.Li 0
370and
371.Fa *tptrp
372points to the 8-
373bit option type field for the option of the specified type.
374If an
375option of the specified type is not located, the return value is
376.Li -1
377and
378.Fa *tptrp
379is
380.Dv NULL .
381If an error occurs, the return value is
382.Li -1
383and
384.Fa *tptrp
385is not
386.Dv NULL .
387.\"
388.Sh EXAMPLES
389RFC 2292 gives comprehensive examples in chapter 6.
390.\"
391.Sh DIAGNOSTICS
392.Fn inet6_option_init
393and
394.Fn inet6_option_append
395return
396.Li 0
397on success or
398.Li -1
399on an error.
400.Pp
401.Fn inet6_option_alloc
402returns
403.Dv NULL
404on an error.
405.Pp
406On errors,
407.Fn inet6_option_next
408and
409.Fn inet6_option_find
410return
411.Li -1
412setting
413.Fa *tptrp
414to non
415.Dv NULL
416value.
417.\"
418.Sh SEE ALSO
419.Rs
420.%A W. Stevens
421.%A M. Thomas
422.%T "Advanced Sockets API for IPv6"
423.%N RFC 2292
424.%D February 1998
425.Re
426.Rs
427.%A S. Deering
428.%A R. Hinden
429.%T "Internet Protocol, Version 6 (IPv6) Specification"
430.%N RFC 2460
431.%D December 1998
432.Re
433.\"
434.Sh STANDARDS
435The functions
436are documented in
437.Dq Advanced Sockets API for IPv6
438.Pq RFC 2292 .
439.\"
440.Sh HISTORY
441The implementation first appeared in KAME advanced networking kit.
442.\"
443.Sh BUGS
444The text was shamelessly copied from RFC 2292.
diff --git a/src/lib/libc/net/inet6_rthdr_space.3 b/src/lib/libc/net/inet6_rthdr_space.3
deleted file mode 100644
index 33b209af4f..0000000000
--- a/src/lib/libc/net/inet6_rthdr_space.3
+++ /dev/null
@@ -1,317 +0,0 @@
1.\" $OpenBSD: inet6_rthdr_space.3,v 1.13 2003/08/08 09:26:02 jmc Exp $
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.Fd #include <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
66RFC 2292 IPv6 advanced API defines eight
67functions that the application calls to build and examine a Routing
68header.
69Four functions build a Routing header:
70.Bl -hang
71.It Fn inet6_rthdr_space
72return #bytes required for ancillary data
73.It Fn inet6_rthdr_init
74initialize ancillary data for Routing header
75.It Fn inet6_rthdr_add
76add IPv6 address & flags to Routing header
77.It Fn inet6_rthdr_lasthop
78specify the flags for the final hop
79.El
80.Pp
81Four functions deal with a returned Routing header:
82.Bl -hang
83.It Fn inet6_rthdr_reverse
84reverse a Routing header
85.It Fn inet6_rthdr_segments
86return #segments in a Routing header
87.It Fn inet6_rthdr_getaddr
88fetch one address from a Routing header
89.It Fn inet6_rthdr_getflags
90fetch one flag from a Routing header
91.El
92.Pp
93The function prototypes for these functions are all in the
94.Aq Pa netinet/in.h
95header.
96.\"
97.Ss inet6_rthdr_space
98This function returns the number of bytes required to hold a Routing
99header of the specified
100.Fa type
101containing the specified number of
102.Fa segments
103.Pq addresses .
104For an IPv6 Type 0 Routing header, the number
105of segments must be between 1 and 23, inclusive.
106The return value
107includes the size of the cmsghdr structure that precedes the Routing
108header, and any required padding.
109.Pp
110If the return value is 0, then either the type of the Routing header
111is not supported by this implementation or the number of segments is
112invalid for this type of Routing header.
113.Pp
114Note: This function returns the size but does not allocate the space
115required for the ancillary data.
116This allows an application to
117allocate a larger buffer, if other ancillary data objects are
118desired, since all the ancillary data objects must be specified to
119.Xr sendmsg 2
120as a single
121.Li msg_control
122buffer.
123.\"
124.Ss inet6_rthdr_init
125This function initializes the buffer pointed to by
126.Fa bp
127to contain a
128.Li cmsghdr
129structure followed by a Routing header of the specified
130.Fa type .
131The
132.Li cmsg_len
133member of the
134.Li cmsghdr
135structure is initialized to the
136size of the structure plus the amount of space required by the
137Routing header.
138The
139.Li cmsg_level
140and
141.Li cmsg_type
142members are also initialized as required.
143.Pp
144The caller must allocate the buffer and its size can be determined by
145calling
146.Fn inet6_rthdr_space .
147.Pp
148Upon success the return value is the pointer to the
149.Li cmsghdr
150structure, and this is then used as the first argument to the next
151two functions.
152Upon an error the return value is
153.Dv NULL .
154.\"
155.Ss inet6_rthdr_add
156This function adds the address pointed to by
157.Fa addr
158to the end of the
159Routing header being constructed and sets the type of this hop to the
160value of
161.Fa flags .
162For an IPv6 Type 0 Routing header,
163.Fa flags
164must be
165either
166.Dv IPV6_RTHDR_LOOSE
167or
168.Dv IPV6_RTHDR_STRICT .
169.Pp
170If successful, the
171.Li cmsg_len
172member of the
173.Li cmsghdr
174structure is
175updated to account for the new address in the Routing header and the
176return value of the function is 0.
177Upon an error the return value of
178the function is -1.
179.\"
180.Ss inet6_rthdr_lasthop
181This function specifies the Strict/Loose flag for the final hop of a
182Routing header.
183For an IPv6 Type 0 Routing header,
184.Fa flags
185must be either
186.Dv IPV6_RTHDR_LOOSE
187or
188.Dv IPV6_RTHDR_STRICT .
189.Pp
190The return value of the function is 0 upon success, or -1 upon an error.
191.Pp
192Notice that a Routing header specifying
193.Li N
194intermediate nodes requires
195.Li N+1
196Strict/Loose flags.
197This requires
198.Li N
199calls to
200.Fn inet6_rthdr_add
201followed by one call to
202.Fn inet6_rthdr_lasthop .
203.\"
204.Ss inet6_rthdr_reverse
205This function takes a Routing header that was received as ancillary
206data
207.Po
208pointed to by the first argument,
209.Fa in
210.Pc
211and writes a new Routing
212header that sends datagrams along the reverse of that route.
213Both
214arguments are allowed to point to the same buffer
215.Pq that is, the reversal can occur in place .
216.Pp
217The return value of the function is 0 on success, or -1 upon an
218error.
219.\"
220.Ss inet6_rthdr_segments
221This function returns the number of segments
222.Pq addresses
223contained in
224the Routing header described by
225.Fa cmsg .
226On success the return value is
227between 1 and 23, inclusive.
228The return value of the function is -1 upon an error.
229.\"
230.Ss inet6_rthdr_getaddr
231This function returns a pointer to the IPv6 address specified by
232.Fa index
233(which must have a value between 1 and the value returned by
234.Fn inet6_rthdr_segments )
235in the Routing header described by
236.Fa cmsg .
237An
238application should first call
239.Fn inet6_rthdr_segments
240to obtain the number of segments in the Routing header.
241.Pp
242Upon an error the return value of the function is
243.Dv NULL .
244.\"
245.Ss inet6_rthdr_getflags
246This function returns the flags value specified by
247.Fa index
248(which must
249have a value between 0 and the value returned by
250.Fn inet6_rthdr_segments )
251in the Routing header described by
252.Fa cmsg .
253For an IPv6 Type 0 Routing header the return value will be either
254.Dv IPV6_RTHDR_LOOSE
255or
256.Dv IPV6_RTHDR_STRICT .
257.Pp
258Upon an error the return value of the function is -1.
259.Pp
260Note: Addresses are indexed starting at 1, and flags starting at 0,
261to maintain consistency with the terminology and figures in RFC 2460.
262.\"
263.Sh EXAMPLES
264RFC 2292 gives comprehensive examples in chapter 8.
265.\"
266.Sh DIAGNOSTICS
267.Fn inet6_rthdr_space
268returns 0 on errors.
269.Pp
270.Fn inet6_rthdr_add ,
271.Fn inet6_rthdr_lasthop
272and
273.Fn inet6_rthdr_reverse
274return 0 on success, and returns -1 on error.
275.Pp
276.Fn inet6_rthdr_init
277and
278.Fn inet6_rthdr_getaddr
279return
280.Dv NULL
281on error.
282.Pp
283.Fn inet6_rthdr_segments
284and
285.Fn inet6_rthdr_getflags
286return -1 on error.
287.\"
288.Sh SEE ALSO
289.Rs
290.%A W. Stevens
291.%A M. Thomas
292.%T "Advanced Sockets API for IPv6"
293.%N RFC 2292
294.%D February 1998
295.Re
296.Rs
297.%A S. Deering
298.%A R. Hinden
299.%T "Internet Protocol, Version 6 (IPv6) Specification"
300.%N RFC 2460
301.%D December 1998
302.Re
303.\"
304.Sh STANDARDS
305The functions
306are documented in
307.Dq Advanced Sockets API for IPv6
308.Pq RFC 2292 .
309.\"
310.Sh HISTORY
311The implementation first appeared in KAME advanced networking kit.
312.\"
313.Sh BUGS
314The text was shamelessly copied from RFC 2292.
315.Pp
316.Fn inet6_rthdr_reverse
317is not implemented yet.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-10-30 05:26:39 +0000