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 $
4 .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
5 .\" Copyright (C) 2000, 2001 Internet Software Consortium.
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.
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.
19 .\" $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.36 2009/01/06 13:10:15 danger Exp $
20 .\" $DragonFly: src/lib/libc/net/getaddrinfo.3,v 1.7 2008/05/22 06:50:14 hasso Exp $
28 .Nd socket address structure to host and service name
37 .Fa "const char *hostname" "const char *servname"
38 .Fa "const struct addrinfo *hints" "struct addrinfo **res"
41 .Fn freeaddrinfo "struct addrinfo *ai"
45 function is used to get a list of
47 addresses and port numbers for host
51 It is a replacement for and provides more flexibility than the
61 arguments are either pointers to NUL-terminated strings or the null pointer.
62 An acceptable value for
64 is either a valid host name or a numeric host address string consisting
65 of a dotted decimal IPv4 address or an IPv6 address.
68 is either a decimal port number or a service name listed in
77 is an optional pointer to a
83 int ai_flags; /* input flags */
84 int ai_family; /* protocol family for socket */
85 int ai_socktype; /* socket type */
86 int ai_protocol; /* protocol for socket */
87 socklen_t ai_addrlen; /* length of socket-address */
88 struct sockaddr *ai_addr; /* socket-address for socket */
89 char *ai_canonname; /* canonical name for service location */
90 struct addrinfo *ai_next; /* pointer to next in list */
94 This structure can be used to provide hints concerning the type of socket
95 that the caller supports or wishes to use.
96 The caller can supply the following structure elements in
98 .Bl -tag -width "ai_socktypeXX"
100 The protocol family that should be used.
105 it means the caller will accept any protocol family supported by the
108 Denotes the type of socket that is wanted:
115 is zero the caller will accept any socket type.
117 Indicates which transport protocol is desired,
123 is zero the caller will accept any protocol.
129 parameter points shall be set to zero
130 or be the bitwise-inclusive OR of one or more of the values
137 .Bl -tag -width "AI_CANONNAMEXX"
141 bit is set, IPv4 addresses shall be returned only if
142 an IPv4 address is configured on the local system,
143 and IPv6 addresses shall be returned only if
144 an IPv6 address is configured on the local system.
148 bit is set, a successful call to
150 will return a NUL-terminated string containing the canonical name
151 of the specified hostname in the
156 .It Dv AI_NUMERICHOST
159 bit is set, it indicates that
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
169 string supplied shall be a numeric port string.
172 error shall be returned.
173 This bit shall prevent any type of name resolution service
174 (for example, NIS+) from being invoked.
178 bit is set it indicates that the returned socket address structure
179 is intended for use in a call to
183 argument is the null pointer, then the IP address portion of the
184 socket address structure will be set to
186 for an IPv4 address or
192 bit is not set, the returned socket address structure will be ready
195 for a connection-oriented protocol or
200 if a connectionless protocol was chosen.
203 address portion of the socket address structure will be set to the
206 is the null pointer and
212 All other elements of the
216 must be zero or the null pointer.
222 behaves as if the caller provided a
228 and all other elements set to zero or
231 After a successful call to
234 is a pointer to a linked list of one or more
237 The list can be traversed by following the
241 structure until a null pointer is encountered.
249 structure are suitable for a call to
253 structure in the list, the
255 member points to a filled-in socket address structure of length
258 This implementation of
260 allows numeric IPv6 address notation with scope identifier,
261 as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
262 By appending the percent character and scope identifier to addresses,
266 This would make management of scoped addresses easier
267 and allows cut-and-paste input of scoped addresses.
269 At this moment the code supports only link-local addresses with the format.
270 The scope identifier is hardcoded to the name of the hardware interface
282 on the link associated with the
287 The current implementation assumes a one-to-one relationship between
288 the interface and link, which is not necessarily true from the specification.
290 All of the information returned by
292 is dynamically allocated: the
294 structures themselves as well as the socket address structures and
295 the canonical host name strings included in the
299 Memory allocated for the dynamically allocated structures created by
309 structure created by a call to
313 returns zero on success or one of the error codes listed in
317 The following code tries to connect to
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
326 Similarly, if it resolves to IPv6, an
329 Observe that there is no hardcoded reference to a particular address family.
330 The code works even if
332 returns addresses that are not IPv4/v6.
333 .Bd -literal -offset indent
334 struct addrinfo hints, *res, *res0;
337 const char *cause = NULL;
339 memset(&hints, 0, sizeof(hints));
340 hints.ai_family = PF_UNSPEC;
341 hints.ai_socktype = SOCK_STREAM;
342 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
344 errx(1, "%s", gai_strerror(error));
348 for (res = res0; res; res = res->ai_next) {
349 s = socket(res->ai_family, res->ai_socktype,
356 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
363 break; /* okay we got one */
372 The following example tries to open a wildcard listening socket onto service
374 for all the address families available.
375 .Bd -literal -offset indent
376 struct addrinfo hints, *res, *res0;
380 const char *cause = NULL;
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, "http", &hints, &res0);
388 errx(1, "%s", gai_strerror(error));
392 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
393 s[nsock] = socket(res->ai_family, res->ai_socktype,
400 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
405 (void) listen(s[nsock], 5);
421 .Xr gethostbyname 3 ,
423 .Xr getservbyname 3 ,
436 .%T Basic Socket Interface Extensions for IPv6
446 .%T "IPv6 Scoped Address Architecture"
448 .%N draft-ietf-ipv6-scoping-arch-02.txt
449 .%O work in progress material
453 .%T Protocol Independence Using the Sockets API
454 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
460 function is defined by the
462 specification and documented in
464 .Dq Basic Socket Interface Extensions for IPv6 .