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 $
3 .\" $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.29 2005/01/23 16:02:48 gnn Exp $
4 .\" $DragonFly: src/lib/libc/net/getaddrinfo.3,v 1.5 2007/04/09 21:20:37 swildner Exp $
6 .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
7 .\" Copyright (C) 2000, 2001 Internet Software Consortium.
9 .\" Permission to use, copy, modify, and distribute this software for any
10 .\" purpose with or without fee is hereby granted, provided that the above
11 .\" copyright notice and this permission notice appear in all copies.
13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
14 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
15 .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
16 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
17 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
18 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
19 .\" PERFORMANCE OF THIS SOFTWARE.
27 .Nd socket address structure to host and service name
33 .Fn getaddrinfo "const char *hostname" "const char *servname" \
34 "const struct addrinfo *hints" "struct addrinfo **res"
36 .Fn freeaddrinfo "struct addrinfo *ai"
40 function is used to get a list of
42 addresses and port numbers for host
46 It is a replacement for and provides more flexibility than the
56 arguments are either pointers to NUL-terminated strings or the null pointer.
57 An acceptable value for
59 is either a valid host name or a numeric host address string consisting
60 of a dotted decimal IPv4 address or an IPv6 address.
63 is either a decimal port number or a service name listed in
72 is an optional pointer to a
78 int ai_flags; /* input flags */
79 int ai_family; /* protocol family for socket */
80 int ai_socktype; /* socket type */
81 int ai_protocol; /* protocol for socket */
82 socklen_t ai_addrlen; /* length of socket-address */
83 struct sockaddr *ai_addr; /* socket-address for socket */
84 char *ai_canonname; /* canonical name for service location */
85 struct addrinfo *ai_next; /* pointer to next in list */
89 This structure can be used to provide hints concerning the type of socket
90 that the caller supports or wishes to use.
91 The caller can supply the following structure elements in
93 .Bl -tag -width "ai_socktypeXX"
95 The protocol family that should be used.
100 it means the caller will accept any protocol family supported by the
103 Denotes the type of socket that is wanted:
110 is zero the caller will accept any socket type.
112 Indicates which transport protocol is desired,
118 is zero the caller will accept any protocol.
123 the following values:
124 .Bl -tag -width "AI_CANONNAMEXX"
128 bit is set, a successful call to
130 will return a NUL-terminated string containing the canonical name
131 of the specified hostname in the
136 .It Dv AI_NUMERICHOST
139 bit is set, it indicates that
141 should be treated as a numeric string defining an IPv4 or IPv6 address
142 and no name resolution should be attempted.
146 bit is set it indicates that the returned socket address structure
147 is intended for use in a call to
151 argument is the null pointer, then the IP address portion of the
152 socket address structure will be set to
154 for an IPv4 address or
160 bit is not set, the returned socket address structure will be ready
163 for a connection-oriented protocol or
168 if a connectionless protocol was chosen.
171 address portion of the socket address structure will be set to the
174 is the null pointer and
180 All other elements of the
184 must be zero or the null pointer.
190 behaves as if the caller provided a
196 and all other elements set to zero or
199 After a successful call to
202 is a pointer to a linked list of one or more
205 The list can be traversed by following the
209 structure until a null pointer is encountered.
217 structure are suitable for a call to
221 structure in the list, the
223 member points to a filled-in socket address structure of length
226 This implementation of
228 allows numeric IPv6 address notation with scope identifier,
229 as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
230 By appending the percent character and scope identifier to addresses,
234 This would make management of scoped addresses easier
235 and allows cut-and-paste input of scoped addresses.
237 At this moment the code supports only link-local addresses with the format.
238 The scope identifier is hardcoded to the name of the hardware interface
250 on the link associated with the
255 The current implementation assumes a one-to-one relationship between
256 the interface and link, which is not necessarily true from the specification.
258 All of the information returned by
260 is dynamically allocated: the
262 structures themselves as well as the socket address structures and
263 the canonical host name strings included in the
267 Memory allocated for the dynamically allocated structures created by
277 structure created by a call to
281 returns zero on success or one of the error codes listed in
285 The following code tries to connect to
290 It loops through all the addresses available, regardless of address family.
291 If the destination resolves to an IPv4 address, it will use an
294 Similarly, if it resolves to IPv6, an
297 Observe that there is no hardcoded reference to a particular address family.
298 The code works even if
300 returns addresses that are not IPv4/v6.
301 .Bd -literal -offset indent
302 struct addrinfo hints, *res, *res0;
305 const char *cause = NULL;
307 memset(&hints, 0, sizeof(hints));
308 hints.ai_family = PF_UNSPEC;
309 hints.ai_socktype = SOCK_STREAM;
310 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
312 errx(1, "%s", gai_strerror(error));
316 for (res = res0; res; res = res->ai_next) {
317 s = socket(res->ai_family, res->ai_socktype,
324 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
331 break; /* okay we got one */
340 The following example tries to open a wildcard listening socket onto service
342 for all the address families available.
343 .Bd -literal -offset indent
344 struct addrinfo hints, *res, *res0;
348 const char *cause = NULL;
350 memset(&hints, 0, sizeof(hints));
351 hints.ai_family = PF_UNSPEC;
352 hints.ai_socktype = SOCK_STREAM;
353 hints.ai_flags = AI_PASSIVE;
354 error = getaddrinfo(NULL, "http", &hints, &res0);
356 errx(1, "%s", gai_strerror(error));
360 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
361 s[nsock] = socket(res->ai_family, res->ai_socktype,
368 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
373 (void) listen(s[nsock], 5);
389 .Xr gethostbyname 3 ,
391 .Xr getservbyname 3 ,
404 .%T Basic Socket Interface Extensions for IPv6
414 .%T "IPv6 Scoped Address Architecture"
416 .%N draft-ietf-ipv6-scoping-arch-02.txt
417 .%O work in progress material
421 .%T Protocol Independence Using the Sockets API
422 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
428 function is defined by the
430 draft specification and documented in
432 .Dq Basic Socket Interface Extensions for IPv6 .
434 The implementation of