xref: /freebsd/lib/libc/net/getaddrinfo.3 (revision 271c3a9060f2ee55607ebe146523f888e1db2654)
1.\"	$KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $
2.\"	$OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $
3.\"
4.\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
5.\" Copyright (C) 2000, 2001  Internet Software Consortium.
6.\"
7.\" Permission to use, copy, modify, and distribute this software for any
8.\" purpose with or without fee is hereby granted, provided that the above
9.\" copyright notice and this permission notice appear in all copies.
10.\"
11.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
12.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
13.\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
14.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
16.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17.\" PERFORMANCE OF THIS SOFTWARE.
18.\"
19.\" $FreeBSD$
20.\"
21.Dd July 1, 2008
22.Dt GETADDRINFO 3
23.Os
24.Sh NAME
25.Nm getaddrinfo ,
26.Nm freeaddrinfo
27.Nd socket address structure to host and service name
28.Sh SYNOPSIS
29.Fd #include <sys/types.h>
30.Fd #include <sys/socket.h>
31.Fd #include <netdb.h>
32.Ft int
33.Fo getaddrinfo
34.Fa "const char *hostname" "const char *servname"
35.Fa "const struct addrinfo *hints" "struct addrinfo **res"
36.Fc
37.Ft void
38.Fn freeaddrinfo "struct addrinfo *ai"
39.Sh DESCRIPTION
40The
41.Fn getaddrinfo
42function is used to get a list of
43.Tn IP
44addresses and port numbers for host
45.Fa hostname
46and service
47.Fa servname .
48It is a replacement for and provides more flexibility than the
49.Xr gethostbyname 3
50and
51.Xr getservbyname 3
52functions.
53.Pp
54The
55.Fa hostname
56and
57.Fa servname
58arguments are either pointers to NUL-terminated strings or the null pointer.
59An acceptable value for
60.Fa hostname
61is either a valid host name or a numeric host address string consisting
62of a dotted decimal IPv4 address or an IPv6 address.
63The
64.Fa servname
65is either a decimal port number or a service name listed in
66.Xr services 5 .
67At least one of
68.Fa hostname
69and
70.Fa servname
71must be non-null.
72.Pp
73.Fa hints
74is an optional pointer to a
75.Li struct addrinfo ,
76as defined by
77.Aq Pa netdb.h :
78.Bd -literal
79struct addrinfo {
80	int ai_flags;		/* input flags */
81	int ai_family;		/* protocol family for socket */
82	int ai_socktype;	/* socket type */
83	int ai_protocol;	/* protocol for socket */
84	socklen_t ai_addrlen;	/* length of socket-address */
85	struct sockaddr *ai_addr; /* socket-address for socket */
86	char *ai_canonname;	/* canonical name for service location */
87	struct addrinfo *ai_next; /* pointer to next in list */
88};
89.Ed
90.Pp
91This structure can be used to provide hints concerning the type of socket
92that the caller supports or wishes to use.
93The caller can supply the following structure elements in
94.Fa hints :
95.Bl -tag -width "ai_socktypeXX"
96.It Fa ai_family
97The protocol family that should be used.
98When
99.Fa ai_family
100is set to
101.Dv PF_UNSPEC ,
102it means the caller will accept any protocol family supported by the
103operating system.
104.It Fa ai_socktype
105Denotes the type of socket that is wanted:
106.Dv SOCK_STREAM ,
107.Dv SOCK_DGRAM ,
108or
109.Dv SOCK_RAW .
110When
111.Fa ai_socktype
112is zero the caller will accept any socket type.
113.It Fa ai_protocol
114Indicates which transport protocol is desired,
115.Dv IPPROTO_UDP
116or
117.Dv IPPROTO_TCP .
118If
119.Fa ai_protocol
120is zero the caller will accept any protocol.
121.It Fa ai_flags
122The
123.Fa ai_flags
124field to which the
125.Fa hints
126parameter points shall be set to zero
127or be the bitwise-inclusive OR of one or more of the values
128.Dv AI_ADDRCONFIG ,
129.Dv AI_ALL ,
130.Dv AI_CANONNAME ,
131.Dv AI_NUMERICHOST ,
132.Dv AI_NUMERICSERV ,
133.Dv AI_PASSIVE ,
134and
135.Dv AI_V4MAPPED .
136.Bl -tag -width "AI_CANONNAMEXX"
137.It Dv AI_ADDRCONFIG
138If the
139.Dv AI_ADDRCONFIG
140bit is set, IPv4 addresses shall be returned only if
141an IPv4 address is configured on the local system,
142and IPv6 addresses shall be returned only if
143an IPv6 address is configured on the local system.
144.It Dv AI_ALL
145If the
146.Dv AI_ALL
147bit is set with the
148.Dv AI_V4MAPPED
149bit, then
150.Fn getaddrinfo
151shall return all matching IPv6 and IPv4 addresses.
152The
153.Dv AI_ALL
154bit without the
155.Dv AI_V4MAPPED
156bit is ignored.
157.It Dv AI_CANONNAME
158If the
159.Dv AI_CANONNAME
160bit is set, a successful call to
161.Fn getaddrinfo
162will return a NUL-terminated string containing the canonical name
163of the specified hostname in the
164.Fa ai_canonname
165element of the first
166.Li addrinfo
167structure returned.
168.It Dv AI_NUMERICHOST
169If the
170.Dv AI_NUMERICHOST
171bit is set, it indicates that
172.Fa hostname
173should be treated as a numeric string defining an IPv4 or IPv6 address
174and no name resolution should be attempted.
175.It Dv AI_NUMERICSERV
176If the
177.Dv AI_NUMERICSERV
178bit is set,
179then a non-null
180.Fa servname
181string supplied shall be a numeric port string.
182Otherwise, an
183.Dv EAI_NONAME
184error shall be returned.
185This bit shall prevent any type of name resolution service
186(for example, NIS+) from being invoked.
187.It Dv AI_PASSIVE
188If the
189.Dv AI_PASSIVE
190bit is set it indicates that the returned socket address structure
191is intended for use in a call to
192.Xr bind 2 .
193In this case, if the
194.Fa hostname
195argument is the null pointer, then the IP address portion of the
196socket address structure will be set to
197.Dv INADDR_ANY
198for an IPv4 address or
199.Dv IN6ADDR_ANY_INIT
200for an IPv6 address.
201.Pp
202If the
203.Dv AI_PASSIVE
204bit is not set, the returned socket address structure will be ready
205for use in a call to
206.Xr connect 2
207for a connection-oriented protocol or
208.Xr connect 2 ,
209.Xr sendto 2 ,
210or
211.Xr sendmsg 2
212if a connectionless protocol was chosen.
213The
214.Tn IP
215address portion of the socket address structure will be set to the
216loopback address if
217.Fa hostname
218is the null pointer and
219.Dv AI_PASSIVE
220is not set.
221.It Dv AI_V4MAPPED
222If the
223.Dv AI_V4MAPPED
224flag is specified along with an
225.Fa ai_family
226of
227.Dv AF_INET6 ,
228then
229.Fn getaddrinfo
230shall return IPv4-mapped IPv6 addresses
231on finding no matching IPv6 addresses (
232.Fa ai_addrlen
233shall be 16).
234The
235.Dv AI_V4MAPPED
236flag shall be ignored unless
237.Fa ai_family
238equals
239.Dv AF_INET6 .
240Note: this flag is currently
241.Em not
242supported, see the
243.Sx BUGS
244section.
245.El
246.El
247.Pp
248All other elements of the
249.Li addrinfo
250structure passed via
251.Fa hints
252must be zero or the null pointer.
253.Pp
254If
255.Fa hints
256is the null pointer,
257.Fn getaddrinfo
258behaves as if the caller provided a
259.Li struct addrinfo
260with
261.Fa ai_family
262set to
263.Dv PF_UNSPEC
264and all other elements set to zero or
265.Dv NULL .
266.Pp
267After a successful call to
268.Fn getaddrinfo ,
269.Fa *res
270is a pointer to a linked list of one or more
271.Li addrinfo
272structures.
273The list can be traversed by following the
274.Fa ai_next
275pointer in each
276.Li addrinfo
277structure until a null pointer is encountered.
278The three members
279.Fa ai_family,
280.Fa ai_socktype,
281and
282.Fa ai_protocol
283in each returned
284.Li addrinfo
285structure are suitable for a call to
286.Xr socket 2 .
287For each
288.Li addrinfo
289structure in the list, the
290.Fa ai_addr
291member points to a filled-in socket address structure of length
292.Fa ai_addrlen .
293.Pp
294This implementation of
295.Fn getaddrinfo
296allows numeric IPv6 address notation with scope identifier,
297as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
298By appending the percent character and scope identifier to addresses,
299one can fill the
300.Li sin6_scope_id
301field for addresses.
302This would make management of scoped addresses easier
303and allows cut-and-paste input of scoped addresses.
304.Pp
305At this moment the code supports only link-local addresses with the format.
306The scope identifier is hardcoded to the name of the hardware interface
307associated
308with the link
309.Po
310such as
311.Li ne0
312.Pc .
313An example is
314.Dq Li fe80::1%ne0 ,
315which means
316.Do
317.Li fe80::1
318on the link associated with the
319.Li ne0
320interface
321.Dc .
322.Pp
323The current implementation assumes a one-to-one relationship between
324the interface and link, which is not necessarily true from the specification.
325.Pp
326All of the information returned by
327.Fn getaddrinfo
328is dynamically allocated: the
329.Li addrinfo
330structures themselves as well as the socket address structures and
331the canonical host name strings included in the
332.Li addrinfo
333structures.
334.Pp
335Memory allocated for the dynamically allocated structures created by
336a successful call to
337.Fn getaddrinfo
338is released by the
339.Fn freeaddrinfo
340function.
341The
342.Fa ai
343pointer should be a
344.Li addrinfo
345structure created by a call to
346.Fn getaddrinfo .
347.Sh RETURN VALUES
348.Fn getaddrinfo
349returns zero on success or one of the error codes listed in
350.Xr gai_strerror 3
351if an error occurs.
352.Sh EXAMPLES
353The following code tries to connect to
354.Dq Li www.kame.net
355service
356.Dq Li http
357via a stream socket.
358It loops through all the addresses available, regardless of address family.
359If the destination resolves to an IPv4 address, it will use an
360.Dv AF_INET
361socket.
362Similarly, if it resolves to IPv6, an
363.Dv AF_INET6
364socket is used.
365Observe that there is no hardcoded reference to a particular address family.
366The code works even if
367.Fn getaddrinfo
368returns addresses that are not IPv4/v6.
369.Bd -literal -offset indent
370struct addrinfo hints, *res, *res0;
371int error;
372int s;
373const char *cause = NULL;
374
375memset(&hints, 0, sizeof(hints));
376hints.ai_family = PF_UNSPEC;
377hints.ai_socktype = SOCK_STREAM;
378error = getaddrinfo("www.kame.net", "http", &hints, &res0);
379if (error) {
380	errx(1, "%s", gai_strerror(error));
381	/*NOTREACHED*/
382}
383s = -1;
384for (res = res0; res; res = res->ai_next) {
385	s = socket(res->ai_family, res->ai_socktype,
386	    res->ai_protocol);
387	if (s < 0) {
388		cause = "socket";
389		continue;
390	}
391
392	if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
393		cause = "connect";
394		close(s);
395		s = -1;
396		continue;
397	}
398
399	break;	/* okay we got one */
400}
401if (s < 0) {
402	err(1, "%s", cause);
403	/*NOTREACHED*/
404}
405freeaddrinfo(res0);
406.Ed
407.Pp
408The following example tries to open a wildcard listening socket onto service
409.Dq Li http ,
410for all the address families available.
411.Bd -literal -offset indent
412struct addrinfo hints, *res, *res0;
413int error;
414int s[MAXSOCK];
415int nsock;
416const char *cause = NULL;
417
418memset(&hints, 0, sizeof(hints));
419hints.ai_family = PF_UNSPEC;
420hints.ai_socktype = SOCK_STREAM;
421hints.ai_flags = AI_PASSIVE;
422error = getaddrinfo(NULL, "http", &hints, &res0);
423if (error) {
424	errx(1, "%s", gai_strerror(error));
425	/*NOTREACHED*/
426}
427nsock = 0;
428for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
429	s[nsock] = socket(res->ai_family, res->ai_socktype,
430	    res->ai_protocol);
431	if (s[nsock] < 0) {
432		cause = "socket";
433		continue;
434	}
435
436	if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
437		cause = "bind";
438		close(s[nsock]);
439		continue;
440	}
441	(void) listen(s[nsock], 5);
442
443	nsock++;
444}
445if (nsock == 0) {
446	err(1, "%s", cause);
447	/*NOTREACHED*/
448}
449freeaddrinfo(res0);
450.Ed
451.Sh SEE ALSO
452.Xr bind 2 ,
453.Xr connect 2 ,
454.Xr send 2 ,
455.Xr socket 2 ,
456.Xr gai_strerror 3 ,
457.Xr gethostbyname 3 ,
458.Xr getnameinfo 3 ,
459.Xr getservbyname 3 ,
460.Xr resolver 3 ,
461.Xr hosts 5 ,
462.Xr resolv.conf 5 ,
463.Xr services 5 ,
464.Xr hostname 7 ,
465.Xr named 8
466.Rs
467.%A R. Gilligan
468.%A S. Thomson
469.%A J. Bound
470.%A J. McCann
471.%A W. Stevens
472.%T Basic Socket Interface Extensions for IPv6
473.%R RFC 3493
474.%D February 2003
475.Re
476.Rs
477.%A S. Deering
478.%A B. Haberman
479.%A T. Jinmei
480.%A E. Nordmark
481.%A B. Zill
482.%T "IPv6 Scoped Address Architecture"
483.%R internet draft
484.%N draft-ietf-ipv6-scoping-arch-02.txt
485.%O work in progress material
486.Re
487.Rs
488.%A Craig Metz
489.%T Protocol Independence Using the Sockets API
490.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
491.%D June 2000
492.Re
493.Sh BUGS
494The
495.Nm
496function as implemented in
497.Fx
498currently does not support
499.Dv AI_ALL
500and
501.Dv AI_V4MAPPED
502flags and returns
503.Dv EAI_BADFLAGS
504if one of them is specified.
505.Sh STANDARDS
506The
507.Fn getaddrinfo
508function is defined by the
509.St -p1003.1-2004
510specification and documented in
511.Dv "RFC 3493" ,
512.Dq Basic Socket Interface Extensions for IPv6 .
513