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