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