xref: /freebsd/lib/libc/net/getaddrinfo.3 (revision 39beb93c3f8bdbf72a61fda42300b5ebed7390c8)
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 January 6, 2009
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_CANONNAME ,
130.Dv AI_NUMERICHOST ,
131.Dv AI_NUMERICSERV
132and
133.Dv AI_PASSIVE .
134.Bl -tag -width "AI_CANONNAMEXX"
135.It Dv AI_ADDRCONFIG
136If the
137.Dv AI_ADDRCONFIG
138bit is set, IPv4 addresses shall be returned only if
139an IPv4 address is configured on the local system,
140and IPv6 addresses shall be returned only if
141an IPv6 address is configured on the local system.
142.It Dv AI_CANONNAME
143If the
144.Dv AI_CANONNAME
145bit is set, a successful call to
146.Fn getaddrinfo
147will return a NUL-terminated string containing the canonical name
148of the specified hostname in the
149.Fa ai_canonname
150element of the first
151.Li addrinfo
152structure returned.
153.It Dv AI_NUMERICHOST
154If the
155.Dv AI_NUMERICHOST
156bit is set, it indicates that
157.Fa hostname
158should be treated as a numeric string defining an IPv4 or IPv6 address
159and no name resolution should be attempted.
160.It Dv AI_NUMERICSERV
161If the
162.Dv AI_NUMERICSERV
163bit is set,
164then a non-null
165.Fa servname
166string supplied shall be a numeric port string.
167Otherwise, an
168.Dv EAI_NONAME
169error shall be returned.
170This bit shall prevent any type of name resolution service
171(for example, NIS+) from being invoked.
172.It Dv AI_PASSIVE
173If the
174.Dv AI_PASSIVE
175bit is set it indicates that the returned socket address structure
176is intended for use in a call to
177.Xr bind 2 .
178In this case, if the
179.Fa hostname
180argument is the null pointer, then the IP address portion of the
181socket address structure will be set to
182.Dv INADDR_ANY
183for an IPv4 address or
184.Dv IN6ADDR_ANY_INIT
185for an IPv6 address.
186.Pp
187If the
188.Dv AI_PASSIVE
189bit is not set, the returned socket address structure will be ready
190for use in a call to
191.Xr connect 2
192for a connection-oriented protocol or
193.Xr connect 2 ,
194.Xr sendto 2 ,
195or
196.Xr sendmsg 2
197if a connectionless protocol was chosen.
198The
199.Tn IP
200address portion of the socket address structure will be set to the
201loopback address if
202.Fa hostname
203is the null pointer and
204.Dv AI_PASSIVE
205is not set.
206.El
207.El
208.Pp
209All other elements of the
210.Li addrinfo
211structure passed via
212.Fa hints
213must be zero or the null pointer.
214.Pp
215If
216.Fa hints
217is the null pointer,
218.Fn getaddrinfo
219behaves as if the caller provided a
220.Li struct addrinfo
221with
222.Fa ai_family
223set to
224.Dv PF_UNSPEC
225and all other elements set to zero or
226.Dv NULL .
227.Pp
228After a successful call to
229.Fn getaddrinfo ,
230.Fa *res
231is a pointer to a linked list of one or more
232.Li addrinfo
233structures.
234The list can be traversed by following the
235.Fa ai_next
236pointer in each
237.Li addrinfo
238structure until a null pointer is encountered.
239The three members
240.Fa ai_family,
241.Fa ai_socktype,
242and
243.Fa ai_protocol
244in each returned
245.Li addrinfo
246structure are suitable for a call to
247.Xr socket 2 .
248For each
249.Li addrinfo
250structure in the list, the
251.Fa ai_addr
252member points to a filled-in socket address structure of length
253.Fa ai_addrlen .
254.Pp
255This implementation of
256.Fn getaddrinfo
257allows numeric IPv6 address notation with scope identifier,
258as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
259By appending the percent character and scope identifier to addresses,
260one can fill the
261.Li sin6_scope_id
262field for addresses.
263This would make management of scoped addresses easier
264and allows cut-and-paste input of scoped addresses.
265.Pp
266At this moment the code supports only link-local addresses with the format.
267The scope identifier is hardcoded to the name of the hardware interface
268associated
269with the link
270.Po
271such as
272.Li ne0
273.Pc .
274An example is
275.Dq Li fe80::1%ne0 ,
276which means
277.Do
278.Li fe80::1
279on the link associated with the
280.Li ne0
281interface
282.Dc .
283.Pp
284The current implementation assumes a one-to-one relationship between
285the interface and link, which is not necessarily true from the specification.
286.Pp
287All of the information returned by
288.Fn getaddrinfo
289is dynamically allocated: the
290.Li addrinfo
291structures themselves as well as the socket address structures and
292the canonical host name strings included in the
293.Li addrinfo
294structures.
295.Pp
296Memory allocated for the dynamically allocated structures created by
297a successful call to
298.Fn getaddrinfo
299is released by the
300.Fn freeaddrinfo
301function.
302The
303.Fa ai
304pointer should be a
305.Li addrinfo
306structure created by a call to
307.Fn getaddrinfo .
308.Sh RETURN VALUES
309.Fn getaddrinfo
310returns zero on success or one of the error codes listed in
311.Xr gai_strerror 3
312if an error occurs.
313.Sh EXAMPLES
314The following code tries to connect to
315.Dq Li www.kame.net
316service
317.Dq Li http
318via a stream socket.
319It loops through all the addresses available, regardless of address family.
320If the destination resolves to an IPv4 address, it will use an
321.Dv AF_INET
322socket.
323Similarly, if it resolves to IPv6, an
324.Dv AF_INET6
325socket is used.
326Observe that there is no hardcoded reference to a particular address family.
327The code works even if
328.Fn getaddrinfo
329returns addresses that are not IPv4/v6.
330.Bd -literal -offset indent
331struct addrinfo hints, *res, *res0;
332int error;
333int s;
334const char *cause = NULL;
335
336memset(&hints, 0, sizeof(hints));
337hints.ai_family = PF_UNSPEC;
338hints.ai_socktype = SOCK_STREAM;
339error = getaddrinfo("www.kame.net", "http", &hints, &res0);
340if (error) {
341	errx(1, "%s", gai_strerror(error));
342	/*NOTREACHED*/
343}
344s = -1;
345for (res = res0; res; res = res->ai_next) {
346	s = socket(res->ai_family, res->ai_socktype,
347	    res->ai_protocol);
348	if (s < 0) {
349		cause = "socket";
350		continue;
351	}
352
353	if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
354		cause = "connect";
355		close(s);
356		s = -1;
357		continue;
358	}
359
360	break;	/* okay we got one */
361}
362if (s < 0) {
363	err(1, "%s", cause);
364	/*NOTREACHED*/
365}
366freeaddrinfo(res0);
367.Ed
368.Pp
369The following example tries to open a wildcard listening socket onto service
370.Dq Li http ,
371for all the address families available.
372.Bd -literal -offset indent
373struct addrinfo hints, *res, *res0;
374int error;
375int s[MAXSOCK];
376int nsock;
377const char *cause = NULL;
378
379memset(&hints, 0, sizeof(hints));
380hints.ai_family = PF_UNSPEC;
381hints.ai_socktype = SOCK_STREAM;
382hints.ai_flags = AI_PASSIVE;
383error = getaddrinfo(NULL, "http", &hints, &res0);
384if (error) {
385	errx(1, "%s", gai_strerror(error));
386	/*NOTREACHED*/
387}
388nsock = 0;
389for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
390	s[nsock] = socket(res->ai_family, res->ai_socktype,
391	    res->ai_protocol);
392	if (s[nsock] < 0) {
393		cause = "socket";
394		continue;
395	}
396
397	if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
398		cause = "bind";
399		close(s[nsock]);
400		continue;
401	}
402	(void) listen(s[nsock], 5);
403
404	nsock++;
405}
406if (nsock == 0) {
407	err(1, "%s", cause);
408	/*NOTREACHED*/
409}
410freeaddrinfo(res0);
411.Ed
412.Sh SEE ALSO
413.Xr bind 2 ,
414.Xr connect 2 ,
415.Xr send 2 ,
416.Xr socket 2 ,
417.Xr gai_strerror 3 ,
418.Xr gethostbyname 3 ,
419.Xr getnameinfo 3 ,
420.Xr getservbyname 3 ,
421.Xr resolver 3 ,
422.Xr hosts 5 ,
423.Xr resolv.conf 5 ,
424.Xr services 5 ,
425.Xr hostname 7 ,
426.Xr named 8
427.Rs
428.%A R. Gilligan
429.%A S. Thomson
430.%A J. Bound
431.%A J. McCann
432.%A W. Stevens
433.%T Basic Socket Interface Extensions for IPv6
434.%R RFC 3493
435.%D February 2003
436.Re
437.Rs
438.%A S. Deering
439.%A B. Haberman
440.%A T. Jinmei
441.%A E. Nordmark
442.%A B. Zill
443.%T "IPv6 Scoped Address Architecture"
444.%R internet draft
445.%N draft-ietf-ipv6-scoping-arch-02.txt
446.%O work in progress material
447.Re
448.Rs
449.%A Craig Metz
450.%T Protocol Independence Using the Sockets API
451.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
452.%D June 2000
453.Re
454.Sh STANDARDS
455The
456.Fn getaddrinfo
457function is defined by the
458.St -p1003.1-2004
459specification and documented in
460.Dv "RFC 3493" ,
461.Dq Basic Socket Interface Extensions for IPv6 .
462