summaryrefslogtreecommitdiff
path: root/src/lib/libc/net/getaddrinfo.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/net/getaddrinfo.3')
-rw-r--r--src/lib/libc/net/getaddrinfo.3470
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
36The
37.Fn getaddrinfo
38function is used to get a list of
39.Tn IP
40addresses and port numbers for host
41.Fa hostname
42and service
43.Fa servname .
44It is a replacement for and provides more flexibility than the
45.Xr gethostbyname 3
46and
47.Xr getservbyname 3
48functions.
49.Pp
50The
51.Fa hostname
52and
53.Fa servname
54arguments are either pointers to NUL-terminated strings or the null pointer.
55An acceptable value for
56.Fa hostname
57is either a valid host name or a numeric host address string consisting
58of a dotted decimal IPv4 address or an IPv6 address.
59The
60.Fa servname
61is either a decimal port number or a service name listed in
62.Xr services 5 .
63At least one of
64.Fa hostname
65and
66.Fa servname
67must be non-null.
68.Pp
69.Fa hints
70is an optional pointer to a
71.Li struct addrinfo ,
72as defined by
73.Aq Pa netdb.h :
74.Bd -literal
75struct 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
87This structure can be used to provide hints concerning the type of socket
88that the caller supports or wishes to use.
89The caller can supply the following structure elements in
90.Fa hints :
91.Bl -tag -width "ai_socktypeXX"
92.It Fa ai_family
93The protocol family that should be used.
94When
95.Fa ai_family
96is set to
97.Dv PF_UNSPEC ,
98it means the caller will accept any protocol family supported by the
99operating system.
100.It Fa ai_socktype
101Denotes the type of socket that is wanted:
102.Dv SOCK_STREAM ,
103.Dv SOCK_DGRAM ,
104or
105.Dv SOCK_RAW .
106When
107.Fa ai_socktype
108is zero the caller will accept any socket type.
109.It Fa ai_protocol
110Indicates which transport protocol is desired,
111.Dv IPPROTO_UDP
112or
113.Dv IPPROTO_TCP .
114If
115.Fa ai_protocol
116is zero the caller will accept any protocol.
117.It Fa ai_flags
118.Fa ai_flags
119is formed by
120.Tn OR Ns 'ing
121the following values:
122.Bl -tag -width "AI_CANONNAMEXX"
123.It Dv AI_CANONNAME
124If the
125.Dv AI_CANONNAME
126bit is set, a successful call to
127.Fn getaddrinfo
128will return a NUL-terminated string containing the canonical name
129of the specified host name in the
130.Fa ai_canonname
131element of the first
132.Li addrinfo
133structure returned.
134.It Dv AI_FQDN
135If the
136.Dv AI_FQDN
137bit is set, a successful call to
138.Fn getaddrinfo
139will return a NUL-terminated string containing the fully qualified domain name
140of the specified host name in the
141.Fa ai_canonname
142element of the first
143.Li addrinfo
144structure returned.
145.Pp
146This is different from the
147.Dv AI_CANONNAME
148bit flag that returns the canonical name registered in DNS,
149which may be different from the fully qualified domain name
150that the host name resolved to.
151Only one of the
152.Dv AI_FQDN
153and
154.Dv AI_CANONNAME
155bits can be set.
156.It Dv AI_NUMERICHOST
157If the
158.Dv AI_NUMERICHOST
159bit is set, it indicates that
160.Fa hostname
161should be treated as a numeric string defining an IPv4 or IPv6 address
162and no name resolution should be attempted.
163.It Dv AI_NUMERICSERV
164If the
165.Dv AI_NUMERICSERV
166bit is set, it indicates that
167.Fa servname
168should be treated as a numeric port string
169and no service name resolution should be attempted.
170.It Dv AI_PASSIVE
171If the
172.Dv AI_PASSIVE
173bit is set it indicates that the returned socket address structure
174is intended for use in a call to
175.Xr bind 2 .
176In this case, if the
177.Fa hostname
178argument is the null pointer, then the IP address portion of the
179socket address structure will be set to
180.Dv INADDR_ANY
181for an IPv4 address or
182.Dv IN6ADDR_ANY_INIT
183for an IPv6 address.
184.Pp
185If the
186.Dv AI_PASSIVE
187bit is not set, the returned socket address structure will be ready
188for use in a call to
189.Xr connect 2
190for a connection-oriented protocol or
191.Xr connect 2 ,
192.Xr sendto 2 ,
193or
194.Xr sendmsg 2
195if a connectionless protocol was chosen.
196The
197.Tn IP
198address portion of the socket address structure will be set to the
199loopback address if
200.Fa hostname
201is the null pointer and
202.Dv AI_PASSIVE
203is not set.
204.El
205.El
206.Pp
207All other elements of the
208.Li addrinfo
209structure passed via
210.Fa hints
211must be zero or the null pointer.
212.Pp
213If
214.Fa hints
215is the null pointer,
216.Fn getaddrinfo
217behaves as if the caller provided a
218.Li struct addrinfo
219with
220.Fa ai_family
221set to
222.Dv PF_UNSPEC
223and all other elements set to zero or
224.Dv NULL .
225.Pp
226After a successful call to
227.Fn getaddrinfo ,
228.Fa *res
229is a pointer to a linked list of one or more
230.Li addrinfo
231structures.
232The list can be traversed by following the
233.Fa ai_next
234pointer in each
235.Li addrinfo
236structure until a null pointer is encountered.
237The three members
238.Fa ai_family ,
239.Fa ai_socktype ,
240and
241.Fa ai_protocol
242in each returned
243.Li addrinfo
244structure are suitable for a call to
245.Xr socket 2 .
246For each
247.Li addrinfo
248structure in the list, the
249.Fa ai_addr
250member points to a filled-in socket address structure of length
251.Fa ai_addrlen .
252.Pp
253This implementation of
254.Fn getaddrinfo
255allows numeric IPv6 address notation with scope identifier,
256as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
257By appending the percent character and scope identifier to addresses,
258one can fill the
259.Li sin6_scope_id
260field for addresses.
261This would make management of scoped addresses easier
262and allows cut-and-paste input of scoped addresses.
263.Pp
264At this moment the code supports only link-local addresses with the format.
265The scope identifier is hardcoded to the name of the hardware interface
266associated
267with the link
268.Po
269such as
270.Li ne0
271.Pc .
272An example is
273.Dq Li fe80::1%ne0 ,
274which means
275.Do
276.Li fe80::1
277on the link associated with the
278.Li ne0
279interface
280.Dc .
281.Pp
282The current implementation assumes a one-to-one relationship between
283the interface and link, which is not necessarily true from the specification.
284.Pp
285All of the information returned by
286.Fn getaddrinfo
287is dynamically allocated: the
288.Li addrinfo
289structures themselves as well as the socket address structures and
290the canonical host name strings included in the
291.Li addrinfo
292structures.
293.Pp
294Memory allocated for the dynamically allocated structures created by
295a successful call to
296.Fn getaddrinfo
297is released by the
298.Fn freeaddrinfo
299function.
300The
301.Fa ai
302pointer should be a
303.Li addrinfo
304structure created by a call to
305.Fn getaddrinfo .
306.Sh RETURN VALUES
307.Fn getaddrinfo
308returns zero on success or one of the error codes listed in
309.Xr gai_strerror 3
310if an error occurs.
311If an error occurs, no memory is allocated by
312.Fn getaddrinfo ,
313therefore it is not necessary to release the
314.Li addrinfo
315structure(s).
316.Sh EXAMPLES
317The following code tries to connect to
318.Dq Li www.kame.net
319service
320.Dq Li www
321via a stream socket.
322It loops through all the addresses available, regardless of address family.
323If the destination resolves to an IPv4 address, it will use an
324.Dv AF_INET
325socket.
326Similarly, if it resolves to IPv6, an
327.Dv AF_INET6
328socket is used.
329Observe that there is no hardcoded reference to a particular address family.
330The code works even if
331.Fn getaddrinfo
332returns addresses that are not IPv4/v6.
333.Bd -literal -offset indent
334struct addrinfo hints, *res, *res0;
335int error;
336int save_errno;
337int s;
338const char *cause = NULL;
339
340memset(&hints, 0, sizeof(hints));
341hints.ai_family = PF_UNSPEC;
342hints.ai_socktype = SOCK_STREAM;
343error = getaddrinfo("www.kame.net", "www", &hints, &res0);
344if (error)
345 errx(1, "%s", gai_strerror(error));
346s = -1;
347for (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}
366if (s == -1)
367 err(1, "%s", cause);
368freeaddrinfo(res0);
369.Ed
370.Pp
371The following example tries to open a wildcard listening socket onto service
372.Dq Li www ,
373for all the address families available.
374.Bd -literal -offset indent
375struct addrinfo hints, *res, *res0;
376int error;
377int save_errno;
378int s[MAXSOCK];
379int nsock;
380const char *cause = NULL;
381
382memset(&hints, 0, sizeof(hints));
383hints.ai_family = PF_UNSPEC;
384hints.ai_socktype = SOCK_STREAM;
385hints.ai_flags = AI_PASSIVE;
386error = getaddrinfo(NULL, "www", &hints, &res0);
387if (error)
388 errx(1, "%s", gai_strerror(error));
389nsock = 0;
390for (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}
409if (nsock == 0)
410 err(1, "%s", cause);
411freeaddrinfo(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
456The
457.Fn getaddrinfo
458function is defined by the
459.St -p1003.1g-2000
460draft specification and documented in
461.Dv "RFC 3493" ,
462.Dq Basic Socket Interface Extensions for IPv6 .
463.Pp
464The
465.Dv AI_FQDN
466flag bit first appeared in Windows 7.
467.Sh BUGS
468The implementation of
469.Fn getaddrinfo
470is not thread-safe.