| blob | ca0a9035454ccbe61cf4618fa6238b7610f78586 |
1 .\" $NetBSD: getaddrinfo.3,v 1.55 2010/04/17 20:28:47 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 17, 2010
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 .El
203 .El
204 .Pp
205 All other elements of the
206 .Li addrinfo
207 structure passed via
208 .Fa hints
209 must be zero or the null pointer.
210 .Pp
211 If
212 .Fa hints
213 is the null pointer,
214 .Fn getaddrinfo
215 behaves as if the caller provided a
216 .Li struct addrinfo
217 with
218 .Fa ai_family
219 set to
220 .Dv AF_UNSPEC
221 and all other elements set to zero or
222 .Dv NULL .
223 .Pp
224 After a successful call to
225 .Fn getaddrinfo ,
226 .Fa *res
227 is a pointer to a linked list of one or more
228 .Li addrinfo
229 structures.
230 The list can be traversed by following the
231 .Fa ai_next
232 pointer in each
233 .Li addrinfo
234 structure until a null pointer is encountered.
235 The three members
236 .Fa ai_family ,
237 .Fa ai_socktype ,
238 and
239 .Fa ai_protocol
240 in each returned
241 .Li addrinfo
242 structure are suitable for a call to
243 .Xr socket 2 .
244 For each
245 .Li addrinfo
246 structure in the list, the
247 .Fa ai_addr
248 member points to a filled-in socket address structure of length
249 .Fa ai_addrlen .
250 .Pp
251 This implementation of
252 .Fn getaddrinfo
253 allows numeric IPv6 address notation with scope identifier,
254 as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
255 By appending the percent character and scope identifier to addresses,
256 one can fill the
257 .Li sin6_scope_id
258 field for addresses.
259 This would make management of scoped addresses easier
260 and allows cut-and-paste input of scoped addresses.
261 .Pp
262 At this moment the code supports only link-local addresses with the format.
263 The scope identifier is hardcoded to the name of the hardware interface
264 associated
265 with the link
266 .Po
267 such as
268 .Li ne0
269 .Pc .
270 An example is
271 .Dq Li fe80::1%ne0 ,
272 which means
273 .Do
274 .Li fe80::1
275 on the link associated with the
276 .Li ne0
277 interface
278 .Dc .
279 .Pp
280 The current implementation assumes a one-to-one relationship between
281 the interface and link, which is not necessarily true from the specification.
282 .Pp
283 All of the information returned by
284 .Fn getaddrinfo
285 is dynamically allocated: the
286 .Li addrinfo
287 structures themselves as well as the socket address structures and
288 the canonical host name strings included in the
289 .Li addrinfo
290 structures.
291 .Pp
292 Memory allocated for the dynamically allocated structures created by
293 a successful call to
294 .Fn getaddrinfo
295 is released by the
296 .Fn freeaddrinfo
297 function.
298 The
299 .Fa ai
300 pointer should be an
301 .Li addrinfo
302 structure created by a call to
303 .Fn getaddrinfo
304 or
305 .Fn allocaddrinfo .
306 The
307 .Fn allocaddrinfo
308 function is intended primarily for authors of
309 .Xr nsdispatch 3
310 plugins implementing
311 .Fn getaddrinfo
312 backends.
313 .Fn allocaddrinfo
314 allocates a
315 .Li struct addrinfo
316 in a way that is compatible with being returned from
317 .Fn getaddrinfo
318 and being ultimately freed by
319 .Fn freeaddrinfo .
320 The returned structure is zeroed, except for the
321 .Fa ai_addr
322 field, which
323 will point to
324 .Fa len
325 bytes of memory for storage of a socket address.
326 It is safe to allocate memory separately for
327 .Fa ai_canonname
328 with
329 .Xr malloc 3 ,
330 or in any other way that is compatible with deallocation by
331 .Xr free 3 .
332 .Sh RETURN VALUES
333 .Fn getaddrinfo
334 returns zero on success or one of the error codes listed in
335 .Xr gai_strerror 3
336 if an error occurs.
337 .Sh EXAMPLES
338 The following code tries to connect to
339 .Dq Li www.kame.net
340 service
341 .Dq Li http
342 via a stream socket.
343 It loops through all the addresses available, regardless of address family.
344 If the destination resolves to an IPv4 address, it will use an
345 .Dv AF_INET
346 socket.
347 Similarly, if it resolves to IPv6, an
348 .Dv AF_INET6
349 socket is used.
350 Observe that there is no hardcoded reference to a particular address family.
351 The code works even if
352 .Fn getaddrinfo
353 returns addresses that are not IPv4/v6.
354 .Bd -literal -offset indent
355 struct addrinfo hints, *res, *res0;
356 int error;
357 int s;
358 const char *cause = NULL;
360 memset(\*[Am]hints, 0, sizeof(hints));
361 hints.ai_family = AF_UNSPEC;
362 hints.ai_socktype = SOCK_STREAM;
363 error = getaddrinfo("www.kame.net", "http", \*[Am]hints, \*[Am]res0);
364 if (error) {
365 errx(1, "%s", gai_strerror(error));
366 /*NOTREACHED*/
367 }
368 s = -1;
369 for (res = res0; res; res = res-\*[Gt]ai_next) {
370 s = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype,
371 res-\*[Gt]ai_protocol);
372 if (s \*[Lt] 0) {
373 cause = "socket";
374 continue;
375 }
377 if (connect(s, res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) {
378 cause = "connect";
379 close(s);
380 s = -1;
381 continue;
382 }
384 break; /* okay we got one */
385 }
386 if (s \*[Lt] 0) {
387 err(1, "%s", cause);
388 /*NOTREACHED*/
389 }
390 freeaddrinfo(res0);
391 .Ed
392 .Pp
393 The following example tries to open a wildcard listening socket onto service
394 .Dq Li http ,
395 for all the address families available.
396 .Bd -literal -offset indent
397 struct addrinfo hints, *res, *res0;
398 int error;
399 int s[MAXSOCK];
400 int nsock;
401 const char *cause = NULL;
403 memset(\*[Am]hints, 0, sizeof(hints));
404 hints.ai_family = AF_UNSPEC;
405 hints.ai_socktype = SOCK_STREAM;
406 hints.ai_flags = AI_PASSIVE;
407 error = getaddrinfo(NULL, "http", \*[Am]hints, \*[Am]res0);
408 if (error) {
409 errx(1, "%s", gai_strerror(error));
410 /*NOTREACHED*/
411 }
412 nsock = 0;
413 for (res = res0; res \*[Am]\*[Am] nsock \*[Lt] MAXSOCK; res = res-\*[Gt]ai_next) {
414 s[nsock] = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype,
415 res-\*[Gt]ai_protocol);
416 if (s[nsock] \*[Lt] 0) {
417 cause = "socket";
418 continue;
419 }
421 if (bind(s[nsock], res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) {
422 cause = "bind";
423 close(s[nsock]);
424 continue;
425 }
426 (void) listen(s[nsock], 5);
428 nsock++;
429 }
430 if (nsock == 0) {
431 err(1, "%s", cause);
432 /*NOTREACHED*/
433 }
434 freeaddrinfo(res0);
435 .Ed
436 .Sh SEE ALSO
437 .Xr bind 2 ,
438 .Xr connect 2 ,
439 .Xr send 2 ,
440 .Xr socket 2 ,
441 .Xr gai_strerror 3 ,
442 .Xr gethostbyname 3 ,
443 .Xr getnameinfo 3 ,
444 .Xr getservbyname 3 ,
445 .Xr resolver 3 ,
446 .Xr hosts 5 ,
447 .Xr resolv.conf 5 ,
448 .Xr services 5 ,
449 .Xr hostname 7 ,
450 .Xr named 8
451 .Rs
452 .%A R. Gilligan
453 .%A S. Thomson
454 .%A J. Bound
455 .%A J. McCann
456 .%A W. Stevens
457 .%T Basic Socket Interface Extensions for IPv6
458 .%R RFC 3493
459 .%D February 2003
460 .Re
461 .Rs
462 .%A S. Deering
463 .%A B. Haberman
464 .%A T. Jinmei
465 .%A E. Nordmark
466 .%A B. Zill
467 .%T "IPv6 Scoped Address Architecture"
468 .%R internet draft
469 .%N draft-ietf-ipv6-scoping-arch-02.txt
470 .%O work in progress material
471 .Re
472 .Rs
473 .%A Craig Metz
474 .%T "Protocol Independence Using the Sockets API"
475 .%I USENIX Association
476 .%B Proceedings of the FREENIX Track: 2000 USENIX Annual Technical Conference
477 .%D June 18-23, 2000
478 .%P 99-108
479 .%U http://www.usenix.org/events/usenix2000/freenix/metzprotocol/metzprotocol.pdf
480 .Re
481 .Sh STANDARDS
482 The
483 .Fn getaddrinfo
484 function is defined by the
485 .St -p1003.1g-2000
486 draft specification and documented in
487 .Dv "RFC 3493" ,
488 .Dq Basic Socket Interface Extensions for IPv6 .