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