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