summaryrefslogtreecommitdiff
path: root/src/lib/libc/net/getaddrinfo.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/net/getaddrinfo.3')
-rw-r--r--src/lib/libc/net/getaddrinfo.3581
1 files changed, 581 insertions, 0 deletions
diff --git a/src/lib/libc/net/getaddrinfo.3 b/src/lib/libc/net/getaddrinfo.3
new file mode 100644
index 0000000000..5c4be16732
--- /dev/null
+++ b/src/lib/libc/net/getaddrinfo.3
@@ -0,0 +1,581 @@
1.\" $OpenBSD: getaddrinfo.3,v 1.20 2002/04/30 16:31:42 mpech 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. All advertising materials mentioning features or use of this software
16.\" must display the following acknowledgement:
17.\" This product includes software developed by the University of
18.\" California, Berkeley and its contributors.
19.\" 4. Neither the name of the University nor the names of its contributors
20.\" may be used to endorse or promote products derived from this software
21.\" without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
36.\"
37.Dd May 25, 1995
38.Dt GETADDRINFO 3
39.Os
40.\"
41.Sh NAME
42.Nm getaddrinfo ,
43.Nm freeaddrinfo ,
44.Nm gai_strerror
45.Nd nodename-to-address translation in protocol-independent manner
46.\"
47.Sh SYNOPSIS
48.Fd #include <sys/types.h>
49.Fd #include <sys/socket.h>
50.Fd #include <netdb.h>
51.Ft int
52.Fn getaddrinfo "const char *nodename" "const char *servname" \
53"const struct addrinfo *hints" "struct addrinfo **res"
54.Ft void
55.Fn freeaddrinfo "struct addrinfo *ai"
56.Ft "char *"
57.Fn gai_strerror "int ecode"
58.\"
59.Sh DESCRIPTION
60The
61.Fn getaddrinfo
62function is defined for protocol-independent nodename-to-address translation.
63It performs the functionality of
64.Xr gethostbyname 3
65and
66.Xr getservbyname 3 ,
67but in a more sophisticated manner.
68.Pp
69The
70.Li addrinfo
71structure is defined as a result of including the
72.Aq Pa netdb.h
73header:
74.Bd -literal -offset
75struct addrinfo { *
76 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
77 int ai_family; /* PF_xxx */
78 int ai_socktype; /* SOCK_xxx */
79 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
80 size_t ai_addrlen; /* length of ai_addr */
81 char *ai_canonname; /* canonical name for nodename */
82 struct sockaddr *ai_addr; /* binary address */
83 struct addrinfo *ai_next; /* next structure in linked list */
84};
85.Ed
86.Pp
87The
88.Fa nodename
89and
90.Fa servname
91arguments are pointers to NUL-terminated strings or
92.Dv NULL .
93One or both of these two arguments must be a non-null pointer.
94In the normal client scenario, both the
95.Fa nodename
96and
97.Fa servname
98are specified.
99In the normal server scenario, only the
100.Fa servname
101is specified.
102A non-null
103.Fa nodename
104string can be either a node name or a numeric host address string
105(i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
106A non-null
107.Fa servname
108string can be either a service name or a decimal port number.
109.Pp
110The caller can optionally pass an
111.Li addrinfo
112structure, pointed to by the third argument,
113to provide hints concerning the type of socket that the caller supports.
114In this
115.Fa hints
116structure all members other than
117.Fa ai_flags ,
118.Fa ai_family ,
119.Fa ai_socktype ,
120and
121.Fa ai_protocol
122must be zero or a null pointer.
123A value of
124.Dv PF_UNSPEC
125for
126.Fa ai_family
127means the caller will accept any protocol family.
128A value of 0 for
129.Fa ai_socktype
130means the caller will accept any socket type.
131A value of 0 for
132.Fa ai_protocol
133means the caller will accept any protocol.
134For example, if the caller handles only TCP and not UDP, then the
135.Fa ai_socktype
136member of the hints structure should be set to
137.Dv SOCK_STREAM
138when
139.Fn getaddrinfo
140is called.
141If the caller handles only IPv4 and not IPv6, then the
142.Fa ai_family
143member of the
144.Fa hints
145structure should be set to
146.Dv PF_INET
147when
148.Fn getaddrinfo
149is called.
150If the third argument to
151.Fn getaddrinfo
152is a null pointer, this is the same as if the caller had filled in an
153.Li addrinfo
154structure initialized to zero with
155.Fa ai_family
156set to
157.Dv PF_UNSPEC .
158.Pp
159Upon successful return a pointer to a linked list of one or more
160.Li addrinfo
161structures is returned through the final argument.
162The caller can process each
163.Li addrinfo
164structure in this list by following the
165.Fa ai_next
166pointer, until a null pointer is encountered.
167In each returned
168.Li addrinfo
169structure the three members
170.Fa ai_family ,
171.Fa ai_socktype ,
172and
173.Fa ai_protocol
174are the corresponding arguments for a call to the
175.Fn socket
176function.
177In each
178.Li addrinfo
179structure the
180.Fa ai_addr
181member points to a filled-in socket address structure whose length is
182specified by the
183.Fa ai_addrlen
184member.
185.Pp
186If the
187.Dv AI_PASSIVE
188bit is set in the
189.Fa ai_flags
190member of the
191.Fa hints
192structure, then the caller plans to use the returned socket address
193structure in a call to
194.Fn bind .
195In this case, if the
196.Fa nodename
197argument is a null pointer, then the IP address portion of the socket
198address structure will be set to
199.Dv INADDR_ANY
200for an IPv4 address or
201.Dv IN6ADDR_ANY_INIT
202for an IPv6 address.
203.Pp
204If the
205.Dv AI_PASSIVE
206bit is not set in the
207.Fa ai_flags
208member of the
209.Fa hints
210structure, then the returned socket address structure will be ready for a
211call to
212.Fn connect
213.Pq for a connection-oriented protocol
214or either
215.Fn connect ,
216.Fn sendto ,
217or
218.Fn sendmsg
219.Pq for a connectionless protocol .
220In this case, if the
221.Fa nodename
222argument is a null pointer, then the IP address portion of the
223socket address structure will be set to the loopback address.
224.Pp
225If the
226.Dv AI_CANONNAME
227bit is set in the
228.Fa ai_flags
229member of the
230.Fa hints
231structure, then upon successful return the
232.Fa ai_canonname
233member of the first
234.Li addrinfo
235structure in the linked list will point to a NUL-terminated string
236containing the canonical name of the specified
237.Fa nodename .
238.Pp
239If the
240.Dv AI_NUMERICHOST
241bit is set in the
242.Fa ai_flags
243member of the
244.Fa hints
245structure, then a non-null
246.Fa nodename
247string must be a numeric host address string.
248Otherwise an error of
249.Dv EAI_NONAME
250is returned.
251This flag prevents any type of name resolution service (e.g., the DNS)
252from being called.
253.Pp
254The arguments to
255.Fn getaddrinfo
256must sufficiently be consistent and unambiguous.
257Here are pitfall cases you may encounter:
258.Bl -bullet
259.It
260.Fn getaddrinfo
261will raise an error if members of the
262.Fa hints
263structure are not consistent.
264For example, for internet address families,
265.Fn getaddrinfo
266will raise an error if you specify
267.Dv SOCK_STREAM
268to
269.Fa ai_socktype
270while you specify
271.Dv IPPROTO_UDP
272to
273.Fa ai_protocol .
274.It
275If you specify a
276.Fa servname
277which is defined only for certain
278.Fa ai_socktype ,
279.Fn getaddrinfo
280will raise an error because the arguments are not consistent.
281For example,
282.Fn getaddrinfo
283will raise an error if you ask for
284.Dq Li tftp
285service on
286.Dv SOCK_STREAM .
287.It
288For internet address families, if you specify
289.Fa servname
290while you set
291.Fa ai_socktype
292to
293.Dv SOCK_RAW ,
294.Fn getaddrinfo
295will raise an error, because service names are not defined for the internet
296.Dv SOCK_RAW
297space.
298.It
299If you specify a numeric
300.Fa servname ,
301while leaving
302.Fa ai_socktype
303and
304.Fa ai_protocol
305unspecified,
306.Fn getaddrinfo
307will raise an error.
308This is because the numeric
309.Fa servname
310does not identify any socket type, and
311.Fn getaddrinfo
312is not allowed to glob the argument in such case.
313.El
314.Pp
315All of the information returned by
316.Fn getaddrinfo
317is dynamically allocated:
318the
319.Li addrinfo
320structures, the socket address structures, and canonical node name
321strings pointed to by the addrinfo structures.
322To return this information to the system the function
323.Fn freeaddrinfo
324is called.
325The
326.Fa addrinfo
327structure pointed to by the
328.Fa ai argument
329is freed, along with any dynamic storage pointed to by the structure.
330This operation is repeated until a
331.Dv NULL
332.Fa ai_next
333pointer is encountered.
334.Pp
335To aid applications in printing error messages based on the
336.Dv EAI_xxx
337codes returned by
338.Fn getaddrinfo ,
339.Fn gai_strerror
340is defined.
341The argument is one of the
342.Dv EAI_xxx
343values defined earlier and the return value points to a string describing
344the error.
345If the argument is not one of the
346.Dv EAI_xxx
347values, the function still returns a pointer to a string whose contents
348indicate an unknown error.
349.\"
350.Ss Extension for scoped IPv6 address
351The implementation allows experimental numeric IPv6 address notation with
352scope identifier.
353By appending the percent character and scope identifier to addresses,
354you can fill
355.Li sin6_scope_id
356field for addresses.
357This would make management of scoped address easier,
358and allows cut-and-paste input of scoped address.
359.Pp
360At this moment the code supports only link-local addresses with the format.
361Scope identifier is hardcoded to name of hardware interface associated
362with the link.
363.Po
364such as
365.Li ne0
366.Pc .
367Example would be like
368.Dq Li fe80::1%ne0 ,
369which means
370.Do
371.Li fe80::1
372on the link associated with
373.Li ne0
374interface
375.Dc .
376.Pp
377The implementation is still very experimental and non-standard.
378The current implementation assumes one-by-one relationship between
379interface and link, which is not necessarily true from the specification.
380.\"
381.Sh EXAMPLES
382The following code tries to connect to
383.Dq Li www.kame.net
384service
385.Dq Li http .
386via stream socket.
387It loops through all the addresses available, regardless from address family.
388If the destination resolves to IPv4 address, it will use
389.Dv AF_INET
390socket.
391Similarly, if it resolves to IPv6,
392.Dv AF_INET6
393socket is used.
394Observe that there is no hardcoded reference to particular address family.
395The code works even if
396.Nm getaddrinfo
397returns addresses that are not IPv4/v6.
398.Bd -literal -offset indent
399struct addrinfo hints, *res, *res0;
400int error;
401int s;
402const char *cause = NULL;
403
404memset(&hints, 0, sizeof(hints));
405hints.ai_family = PF_UNSPEC;
406hints.ai_socktype = SOCK_STREAM;
407error = getaddrinfo("www.kame.net", "http", &hints, &res0);
408if (error) {
409 errx(1, "%s", gai_strerror(error));
410 /*NOTREACHED*/
411}
412s = -1;
413for (res = res0; res; res = res->ai_next) {
414 s = socket(res->ai_family, res->ai_socktype,
415 res->ai_protocol);
416 if (s < 0) {
417 cause = "socket";
418 continue;
419 }
420
421 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
422 cause = "connect";
423 close(s);
424 s = -1;
425 continue;
426 }
427
428 break; /* okay we got one */
429}
430if (s < 0) {
431 err(1, cause);
432 /*NOTREACHED*/
433}
434freeaddrinfo(res0);
435.Ed
436.Pp
437The following example tries to open a wildcard listening socket onto service
438.Dq Li http ,
439for all the address families available.
440.Bd -literal -offset indent
441struct addrinfo hints, *res, *res0;
442int error;
443int s[MAXSOCK];
444int nsock;
445const char *cause = NULL;
446
447memset(&hints, 0, sizeof(hints));
448hints.ai_family = PF_UNSPEC;
449hints.ai_socktype = SOCK_STREAM;
450hints.ai_flags = AI_PASSIVE;
451error = getaddrinfo(NULL, "http", &hints, &res0);
452if (error) {
453 errx(1, "%s", gai_strerror(error));
454 /*NOTREACHED*/
455}
456nsock = 0;
457for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
458 s[nsock] = socket(res->ai_family, res->ai_socktype,
459 res->ai_protocol);
460 if (s[nsock] < 0) {
461 cause = "socket";
462 continue;
463 }
464
465 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
466 cause = "bind";
467 close(s[nsock]);
468 continue;
469 }
470 (void) listen(s[nsock], 5);
471
472 nsock++;
473}
474if (nsock == 0) {
475 err(1, cause);
476 /*NOTREACHED*/
477}
478freeaddrinfo(res0);
479.Ed
480.\"
481.Sh DIAGNOSTICS
482Error return status from
483.Fn getaddrinfo
484is zero on success and non-zero on errors.
485Non-zero error codes are defined in
486.Aq Pa netdb.h ,
487and as follows:
488.Pp
489.Bl -tag -width EAI_ADDRFAMILY -compact
490.It Dv EAI_ADDRFAMILY
491Address family for
492.Fa nodename
493not supported.
494.It Dv EAI_AGAIN
495Temporary failure in name resolution.
496.It Dv EAI_BADFLAGS
497Invalid value for
498.Fa ai_flags .
499.It Dv EAI_FAIL
500Non-recoverable failure in name resolution.
501.It Dv EAI_FAMILY
502.Fa ai_family
503not supported.
504.It Dv EAI_MEMORY
505Memory allocation failure.
506.It Dv EAI_NODATA
507No address associated with
508.Fa nodename .
509.It Dv EAI_NONAME
510.Fa nodename
511nor
512.Fa servname
513provided, or not known.
514.It Dv EAI_SERVICE
515.Fa servname
516not supported for
517.Fa ai_socktype .
518.It Dv EAI_SOCKTYPE
519.Fa ai_socktype
520not supported.
521.It Dv EAI_SYSTEM
522System error returned in
523.Va errno .
524.El
525.Pp
526If called with proper argument,
527.Fn gai_strerror
528returns a pointer to a string describing the given error code.
529If the argument is not one of the
530.Dv EAI_xxx
531values, the function still returns a pointer to a string whose contents
532indicate an unknown error.
533.\"
534.Sh SEE ALSO
535.Xr getnameinfo 3 ,
536.Xr gethostbyname 3 ,
537.Xr getservbyname 3 ,
538.Xr hosts 5 ,
539.Xr resolv.conf 5 ,
540.Xr services 5 ,
541.Xr hostname 7 ,
542.Xr named 8
543.Rs
544.%A R. Gilligan
545.%A S. Thomson
546.%A J. Bound
547.%A W. Stevens
548.%T Basic Socket Interface Extensions for IPv6
549.%R RFC2553
550.%D March 1999
551.Re
552.Rs
553.%A Tatsuya Jinmei
554.%A Atsushi Onoe
555.%T "An Extension of Format for IPv6 Scoped Addresses"
556.%R internet draft
557.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
558.%O work in progress material
559.Re
560.Rs
561.%A Craig Metz
562.%T Protocol Independence Using the Sockets API
563.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
564.%D June 2000
565.Re
566.\"
567.Sh HISTORY
568The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
569.\"
570.Sh STANDARDS
571The
572.Fn getaddrinfo
573function is defined in IEEE POSIX 1003.1g draft specification,
574and documented in
575.Dq Basic Socket Interface Extensions for IPv6
576.Pq RFC2553 .
577.\"
578.Sh BUGS
579The current implementation is not thread-safe.
580.Pp
581The text was shamelessly copied from RFC2553.