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