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.
27 .Nd socket address structure to host and service name
34 .Fa "const char *hostname" "const char *servname"
35 .Fa "const struct addrinfo *hints" "struct addrinfo **res"
38 .Fn freeaddrinfo "struct addrinfo *ai"
42 function is used to get a list of
43 addresses and port numbers for host
47 It is a replacement for and provides more flexibility than the
57 arguments are either pointers to NUL-terminated strings or the null pointer.
58 An acceptable value for
60 is either a valid host name or a numeric host address string consisting
61 of a dotted decimal IPv4 address,
63 or a UNIX-domain address.
66 is either a decimal port number or a service name listed in
75 is an optional pointer to a
81 int ai_flags; /* input flags */
82 int ai_family; /* address family for socket */
83 int ai_socktype; /* socket type */
84 int ai_protocol; /* protocol for socket */
85 socklen_t ai_addrlen; /* length of socket-address */
86 struct sockaddr *ai_addr; /* socket-address for socket */
87 char *ai_canonname; /* canonical name for service location */
88 struct addrinfo *ai_next; /* pointer to next in list */
92 This structure can be used to provide hints concerning the type of socket
93 that the caller supports or wishes to use.
94 The caller can supply the following structure elements in
96 .Bl -tag -width "ai_socktypeXX"
98 The address family that should be used.
103 it means the caller will accept any address family supported by the
106 Denotes the type of socket that is wanted:
114 is zero the caller will accept any socket type.
116 Indicates which transport protocol is desired,
121 .Dv IPPROTO_UDPLITE .
124 is zero the caller will accept any protocol.
130 parameter points shall be set to zero
131 or be the bitwise-inclusive OR of one or more of the values
140 For a UNIX-domain address,
143 .Bl -tag -width "AI_CANONNAMEXX"
147 bit is set, IPv4 addresses shall be returned only if
148 an IPv4 address is configured on the local system,
149 and IPv6 addresses shall be returned only if
150 an IPv6 address is configured on the local system.
154 flag is used with the
158 shall return all matching IPv6 and IPv4 addresses.
160 For example, when using the DNS, queries are made for both AAAA records and A records, and
162 returns the combined results of both queries.
163 Any IPv4 addresses found are returned as IPv4-mapped IPv6 addresses.
173 bit is set, a successful call to
175 will return a NUL-terminated string containing the canonical name
176 of the specified hostname in the
181 .It Dv AI_NUMERICHOST
184 bit is set, it indicates that
186 should be treated as a numeric string defining an IPv4 or IPv6 address
187 and no name resolution should be attempted.
188 .It Dv AI_NUMERICSERV
194 string supplied shall be a numeric port string.
197 error shall be returned.
198 This bit shall prevent any type of name resolution service
199 (for example, NIS+) from being invoked.
203 bit is set it indicates that the returned socket address structure
204 is intended for use in a call to
208 argument is the null pointer, then the IP address portion of the
209 socket address structure will be set to
211 for an IPv4 address or
217 bit is not set, the returned socket address structure will be ready
220 for a connection-oriented protocol or
225 if a connectionless protocol was chosen.
228 address portion of the socket address structure will be set to the
231 is the null pointer and
237 flag is specified along with an ai_family of
241 shall return IPv4-mapped IPv6 addresses on finding no matching IPv6 addresses (
245 For example, when using the DNS, if no AAAA records are found then a query is made for A records and any found are returned as IPv4-mapped IPv6 addresses.
249 flag shall be ignored unless
256 All other elements of the
260 must be zero or the null pointer.
266 behaves as if the caller provided a
272 and all other elements set to zero or
275 After a successful call to
278 is a pointer to a linked list of one or more
281 The list can be traversed by following the
285 structure until a null pointer is encountered.
288 structure contains three members that are suitable for a call to
296 structure in the list, the
298 member points to a filled-in socket address structure of length
301 This implementation of
303 allows numeric IPv6 address notation with scope identifier,
304 as documented in chapter 11 of RFC 4007.
305 By appending the percent character and scope identifier to addresses,
309 This would make management of scoped addresses easier
310 and allows cut-and-paste input of scoped addresses.
312 At this moment the code supports only link-local addresses with the format.
313 The scope identifier is hardcoded to the name of the hardware interface
325 on the link associated with the
330 The current implementation assumes a one-to-one relationship between
331 the interface and link, which is not necessarily true from the specification.
333 All of the information returned by
335 is dynamically allocated: the
337 structures themselves as well as the socket address structures and
338 the canonical host name strings included in the
342 Memory allocated for the dynamically allocated structures created by
352 structure created by a call to
356 returns zero on success or one of the error codes listed in
360 The following code tries to connect to
365 It loops through all the addresses available, regardless of address family.
366 If the destination resolves to an IPv4 address, it will use an
369 Similarly, if it resolves to IPv6, an
372 Observe that there is no hardcoded reference to a particular address family.
373 The code works even if
375 returns addresses that are not IPv4/v6.
376 .Bd -literal -offset indent
377 struct addrinfo hints, *res, *res0;
380 const char *cause = NULL;
382 memset(&hints, 0, sizeof(hints));
383 hints.ai_family = AF_UNSPEC;
384 hints.ai_socktype = SOCK_STREAM;
385 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
387 errx(1, "%s", gai_strerror(error));
391 for (res = res0; res; res = res->ai_next) {
392 s = socket(res->ai_family, res->ai_socktype,
399 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
406 break; /* okay we got one */
415 The following example tries to open a wildcard listening socket onto service
417 for all the address families available.
418 .Bd -literal -offset indent
419 struct addrinfo hints, *res, *res0;
423 const char *cause = NULL;
425 memset(&hints, 0, sizeof(hints));
426 hints.ai_family = AF_UNSPEC;
427 hints.ai_socktype = SOCK_STREAM;
428 hints.ai_flags = AI_PASSIVE;
429 error = getaddrinfo(NULL, "http", &hints, &res0);
431 errx(1, "%s", gai_strerror(error));
435 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
436 s[nsock] = socket(res->ai_family, res->ai_socktype,
443 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
448 (void) listen(s[nsock], 5);
464 .Xr gethostbyname 3 ,
466 .Xr getservbyname 3 ,
482 .%T Basic Socket Interface Extensions for IPv6
492 .%T "IPv6 Scoped Address Architecture"
498 .%T Protocol Independence Using the Sockets API
499 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
505 function is defined by the
507 specification and documented in
509 .Dq Basic Socket Interface Extensions for IPv6 .