]> git.saurik.com Git - apple/libc.git/blame - net/getaddrinfo.3
Libc-262.2.12.tar.gz
[apple/libc.git] / net / getaddrinfo.3
CommitLineData
5b2abdfb
A
1.\" $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.17 2001/10/01 16:08:55 ru Exp $
2.\" $KAME: getaddrinfo.3,v 1.22 2000/08/09 21:16:17 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 LIBRARY
48.Lb libc
49.Sh SYNOPSIS
50.In sys/types.h
51.In sys/socket.h
52.In netdb.h
53.Ft int
54.Fn getaddrinfo "const char *nodename" "const char *servname" \
55"const struct addrinfo *hints" "struct addrinfo **res"
56.Ft void
57.Fn freeaddrinfo "struct addrinfo *ai"
58.Ft "char *"
59.Fn gai_strerror "int ecode"
60.\"
61.Sh DESCRIPTION
62The
63.Fn getaddrinfo
64function is defined for protocol-independent nodename-to-address translation.
65It performs the functionality of
66.Xr gethostbyname 3
67and
68.Xr getservbyname 3 ,
69but in a more sophisticated manner.
70.Pp
71The
72.Li addrinfo
73structure is defined as a result of including the
74.Aq Pa netdb.h
75header:
76.Bd -literal -offset
77struct addrinfo {
78 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
79 int ai_family; /* PF_xxx */
80 int ai_socktype; /* SOCK_xxx */
81 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
82 size_t ai_addrlen; /* length of ai_addr */
83 char *ai_canonname; /* canonical name for nodename */
84 struct sockaddr *ai_addr; /* binary address */
85 struct addrinfo *ai_next; /* next structure in linked list */
86};
87.Ed
88.Pp
89The
90.Fa nodename
91and
92.Fa servname
93arguments are pointers to null-terminated strings or
94.Dv NULL .
95One or both of these two arguments must be a
96.Pf non Dv -NULL
97pointer.
98In the normal client scenario, both the
99.Fa nodename
100and
101.Fa servname
102are specified.
103In the normal server scenario, only the
104.Fa servname
105is specified.
106A
107.Pf non Dv -NULL
108.Fa nodename
109string can be either a node name or a numeric host address string
110(i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
111A
112.Pf non Dv -NULL
113.Fa servname
114string can be either a service name or a decimal port number.
115.Pp
116The caller can optionally pass an
117.Li addrinfo
118structure, pointed to by the third argument,
119to provide hints concerning the type of socket that the caller supports.
120In this
121.Fa hints
122structure all members other than
123.Fa ai_flags ,
124.Fa ai_family ,
125.Fa ai_socktype ,
126and
127.Fa ai_protocol
128must be zero or a
129.Dv NULL
130pointer.
131A value of
132.Dv PF_UNSPEC
133for
134.Fa ai_family
135means the caller will accept any protocol family.
136A value of 0 for
137.Fa ai_socktype
138means the caller will accept any socket type.
139A value of 0 for
140.Fa ai_protocol
141means the caller will accept any protocol.
142For example, if the caller handles only TCP and not UDP, then the
143.Fa ai_socktype
144member of the hints structure should be set to
145.Dv SOCK_STREAM
146when
147.Fn getaddrinfo
148is called.
149If the caller handles only IPv4 and not IPv6, then the
150.Fa ai_family
151member of the
152.Fa hints
153structure should be set to
154.Dv PF_INET
155when
156.Fn getaddrinfo
157is called.
158If the third argument to
159.Fn getaddrinfo
160is a
161.Dv NULL
162pointer, this is the same as if the caller had filled in an
163.Li addrinfo
164structure initialized to zero with
165.Fa ai_family
166set to
167.Dv PF_UNSPEC .
168.Pp
169Upon successful return a pointer to a linked list of one or more
170.Li addrinfo
171structures is returned through the final argument.
172The caller can process each
173.Li addrinfo
174structure in this list by following the
175.Fa ai_next
176pointer, until a
177.Dv NULL
178pointer is encountered.
179In each returned
180.Li addrinfo
181structure the three members
182.Fa ai_family ,
183.Fa ai_socktype ,
184and
185.Fa ai_protocol
186are the corresponding arguments for a call to the
187.Fn socket
188function.
189In each
190.Li addrinfo
191structure the
192.Fa ai_addr
193member points to a filled-in socket address structure whose length is
194specified by the
195.Fa ai_addrlen
196member.
197.Pp
198If the
199.Dv AI_PASSIVE
200bit is set in the
201.Fa ai_flags
202member of the
203.Fa hints
204structure, then the caller plans to use the returned socket address
205structure in a call to
206.Fn bind .
207In this case, if the
208.Fa nodename
209argument is a
210.Dv NULL
211pointer, then the IP address portion of the socket
212address structure will be set to
213.Dv INADDR_ANY
214for an IPv4 address or
215.Dv IN6ADDR_ANY_INIT
216for an IPv6 address.
217.Pp
218If the
219.Dv AI_PASSIVE
220bit is not set in the
221.Fa ai_flags
222member of the
223.Fa hints
224structure, then the returned socket address structure will be ready for a
225call to
226.Fn connect
227(for a connection-oriented protocol)
228or either
229.Fn connect ,
230.Fn sendto ,
231or
232.Fn sendmsg
233(for a connectionless protocol).
234In this case, if the
235.Fa nodename
236argument is a
237.Dv NULL
238pointer, then the IP address portion of the
239socket address structure will be set to the loopback address.
240.Pp
241If the
242.Dv AI_CANONNAME
243bit is set in the
244.Fa ai_flags
245member of the
246.Fa hints
247structure, then upon successful return the
248.Fa ai_canonname
249member of the first
250.Li addrinfo
251structure in the linked list will point to a null-terminated string
252containing the canonical name of the specified
253.Fa nodename .
254.Pp
255If the
256.Dv AI_NUMERICHOST
257bit is set in the
258.Fa ai_flags
259member of the
260.Fa hints
261structure, then a
262.Pf non Dv -NULL
263.Fa nodename
264string must be a numeric host address string.
265Otherwise an error of
266.Dv EAI_NONAME
267is returned.
268This flag prevents any type of name resolution service (e.g., the DNS)
269from being called.
270.Pp
271The arguments to
272.Fn getaddrinfo
273must be sufficiently consistent and unambiguous.
274Here are some problem cases you may encounter:
275.Bl -bullet
276.It
277.Fn getaddrinfo
278will fail if the members in the
279.Fa hints
280structure are not consistent.
281For example, for internet address families,
282.Fn getaddrinfo
283will fail if you specify
284.Dv SOCK_STREAM
285to
286.Fa ai_socktype
287while you specify
288.Dv IPPROTO_UDP
289to
290.Fa ai_protocol .
291.It
292If you specify a
293.Fa servname
294which is defined only for certain
295.Fa ai_socktype ,
296.Fn getaddrinfo
297will fail because the arguments are not consistent.
298For example,
299.Fn getaddrinfo
300will return an error if you ask for
301.Dq Li tftp
302service on
303.Dv SOCK_STREAM .
304.It
305For internet address families, if you specify
306.Fa servname
307while you set
308.Fa ai_socktype
309to
310.Dv SOCK_RAW ,
311.Fn getaddrinfo
312will fail, because service names are not defined for the internet
313.Dv SOCK_RAW
314space.
315.It
316If you specify numeric
317.Fa servname ,
318while leaving
319.Fa ai_socktype
320and
321.Fa ai_protocol
322unspecified,
323.Fn getaddrinfo
324will fail.
325This is because the numeric
326.Fa servname
327does not identify any socket type, and
328.Fn getaddrinfo
329is not allowed to glob the argument in such case.
330.El
331.Pp
332All of the information returned by
333.Fn getaddrinfo
334is dynamically allocated:
335the
336.Li addrinfo
337structures, the socket address structures, and canonical node name
338strings pointed to by the addrinfo structures.
339To return this information to the system the function
340.Fn freeaddrinfo
341is called.
342The
343.Fa addrinfo
344structure pointed to by the
345.Fa ai argument
346is freed, along with any dynamic storage pointed to by the structure.
347This operation is repeated until a
348.Dv NULL
349.Fa ai_next
350pointer is encountered.
351.Pp
352To aid applications in printing error messages based on the
353.Dv EAI_xxx
354codes returned by
355.Fn getaddrinfo ,
356.Fn gai_strerror
357is defined.
358The argument is one of the
359.Dv EAI_xxx
360values defined earlier and the return value points to a string describing
361the error.
362If the argument is not one of the
363.Dv EAI_xxx
364values, the function still returns a pointer to a string whose contents
365indicate an unknown error.
366.\"
367.Sh EXTENSIONS
368This implementation supports numeric IPv6 address notation with the
369experimental scope identifier.
370By appending a percent sign and scope identifier to the address, you
371can specify the value of the
372.Li sin6_scope_id
373field of the socket address.
374This makes management of scoped address easier,
375and allows cut-and-paste input of scoped addresses.
376.Pp
377At the moment the code supports only link-local addresses in this format.
378The scope identifier is hardcoded to name of hardware interface associated
379with the link,
380(such as
381.Li ne0 ) .
382For example,
383.Dq Li fe80::1%ne0 ,
384which means
385.Do
386.Li fe80::1
387on the link associated with the
388.Li ne0
389interface
390.Dc .
391.Pp
392This implementation is still very experimental and non-standard.
393The current implementation assumes a one-to-one relationship between
394interfaces and links, which is not necessarily true according to the
395specification.
396.\"
397.Sh EXAMPLES
398The following code tries to connect to
399.Dq Li www.kame.net
400service
401.Dq Li http .
402via stream socket.
403It loops through all the addresses available, regardless of the address family.
404If the destination resolves to an IPv4 address, it will use an
405.Dv AF_INET
406socket.
407Similarly, if it resolves to IPv6, an
408.Dv AF_INET6
409socket is used.
410Observe that there is no hardcoded reference to particular address family.
411The code works even if
412.Fn getaddrinfo
413returns addresses that are not IPv4/v6.
414.Bd -literal -offset indent
415struct addrinfo hints, *res, *res0;
416int error;
417int s;
418const char *cause = NULL;
419
420memset(&hints, 0, sizeof(hints));
421hints.ai_family = PF_UNSPEC;
422hints.ai_socktype = SOCK_STREAM;
423error = getaddrinfo("www.kame.net", "http", &hints, &res0);
424if (error) {
425 errx(1, "%s", gai_strerror(error));
426 /*NOTREACHED*/
427}
428s = -1;
429cause = "no addresses";
430errno = EADDRNOTAVAIL;
431for (res = res0; res; res = res->ai_next) {
432 s = socket(res->ai_family, res->ai_socktype,
433 res->ai_protocol);
434 if (s < 0) {
435 cause = "socket";
436 continue;
437 }
438
439 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
440 cause = "connect";
441 close(s);
442 s = -1;
443 continue;
444 }
445
446 break; /* okay we got one */
447}
448if (s < 0) {
449 err(1, cause);
450 /*NOTREACHED*/
451}
452freeaddrinfo(res0);
453.Ed
454.Pp
455The following example tries to open a wildcard listening socket onto service
456.Dq Li http ,
457for all the address families available.
458.Bd -literal -offset indent
459struct addrinfo hints, *res, *res0;
460int error;
461int s[MAXSOCK];
462int nsock;
463const char *cause = NULL;
464
465memset(&hints, 0, sizeof(hints));
466hints.ai_family = PF_UNSPEC;
467hints.ai_socktype = SOCK_STREAM;
468hints.ai_flags = AI_PASSIVE;
469error = getaddrinfo(NULL, "http", &hints, &res0);
470if (error) {
471 errx(1, "%s", gai_strerror(error));
472 /*NOTREACHED*/
473}
474nsock = 0;
475for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
476 s[nsock] = socket(res->ai_family, res->ai_socktype,
477 res->ai_protocol);
478 if (s[nsock] < 0) {
479 cause = "socket";
480 continue;
481 }
482
483 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
484 cause = "bind";
485 close(s[nsock]);
486 continue;
487 }
488
489 if (listen(s[nsock], SOMAXCONN) < 0) {
490 cause = "listen";
491 close(s[nsock]);
492 continue;
493 }
494
495 nsock++;
496}
497if (nsock == 0) {
498 err(1, cause);
499 /*NOTREACHED*/
500}
501freeaddrinfo(res0);
502.Ed
503.\"
504.Sh FILES
505.Bl -tag -width /etc/nsswitch.conf -compact
506.It Pa /etc/hosts
507.It Pa /etc/nsswitch.conf
508.It Pa /etc/resolv.conf
509.El
510.\"
511.Sh DIAGNOSTICS
512Error return status from
513.Fn getaddrinfo
514is zero on success and non-zero on errors.
515Non-zero error codes are defined in
516.Aq Pa netdb.h ,
517and as follows:
518.Pp
519.Bl -tag -width EAI_ADDRFAMILY -compact
520.It Dv EAI_ADDRFAMILY
521Address family for
522.Fa nodename
523not supported.
524.It Dv EAI_AGAIN
525Temporary failure in name resolution.
526.It Dv EAI_BADFLAGS
527Invalid value for
528.Fa ai_flags .
529.It Dv EAI_FAIL
530Non-recoverable failure in name resolution.
531.It Dv EAI_FAMILY
532.Fa ai_family
533not supported.
534.It Dv EAI_MEMORY
535Memory allocation failure.
536.It Dv EAI_NODATA
537No address associated with
538.Fa nodename .
539.It Dv EAI_NONAME
540.Fa nodename
541nor
542.Fa servname
543provided, or not known.
544.It Dv EAI_SERVICE
545.Fa servname
546not supported for
547.Fa ai_socktype .
548.It Dv EAI_SOCKTYPE
549.Fa ai_socktype
550not supported.
551.It Dv EAI_SYSTEM
552System error returned in
553.Va errno .
554.It Dv EAI_BADHINTS
555Invalid value for
556.Fa hints .
557.It Dv EAI_PROTOCOL
558Resolved protocol is unknown.
559.It Dv EAI_MAX
560Unknown error.
561.El
562.Pp
563If called with an appropriate argument,
564.Fn gai_strerror
565returns a pointer to a string describing the given error code.
566If the argument is not one of the
567.Dv EAI_xxx
568values, the function still returns a pointer to a string whose contents
569indicate an unknown error.
570.\"
571.Sh SEE ALSO
572.Xr gethostbyname 3 ,
573.Xr getnameinfo 3 ,
574.Xr getservbyname 3 ,
575.Xr hosts 5 ,
576.Xr services 5 ,
577.Xr hostname 7 ,
578.Xr named 8
579.Pp
580.Rs
581.%A R. Gilligan
582.%A S. Thomson
583.%A J. Bound
584.%A W. Stevens
585.%T Basic Socket Interface Extensions for IPv6
586.%R RFC2553
587.%D March 1999
588.Re
589.Rs
590.%A Tatsuya Jinmei
591.%A Atsushi Onoe
592.%T "An Extension of Format for IPv6 Scoped Addresses"
593.%R internet draft
594.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
595.%O work in progress material
596.Re
597.Rs
598.%A Craig Metz
599.%T Protocol Independence Using the Sockets API
600.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
601.%D June 2000
602.Re
603.\"
604.Sh HISTORY
605The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
606.\"
607.Sh STANDARDS
608The
609.Fn getaddrinfo
610function is defined in
611.St -p1003.1g-2000 ,
612and documented in
613.Dq Basic Socket Interface Extensions for IPv6
614(RFC2553).
615.\"
616.Sh BUGS
617The current implementation is not thread-safe.
618.Pp
619The text was shamelessly copied from RFC2553.