1 .\" $NetBSD: getaddrinfo.3,v 1.39 2005/01/11 06:01:41 itojun Exp $
2 .\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $
3 .\" $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $
5 .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
6 .\" Copyright (C) 2000, 2001 Internet Software Consortium.
8 .\" Permission to use, copy, modify, and distribute this software for any
9 .\" purpose with or without fee is hereby granted, provided that the above
10 .\" copyright notice and this permission notice appear in all copies.
12 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
13 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
14 .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
15 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
16 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
17 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
18 .\" PERFORMANCE OF THIS SOFTWARE.
26 .Nd socket address structure to host and service name
28 .Fd #include <sys/socket.h>
29 .Fd #include <netdb.h>
32 .Fa "struct addrinfo *ai"
36 .Fa "const char *restrict nodename"
37 .Fa "const char *restrict servname"
38 .Fa "const struct addrinfo *restrict hints"
39 .Fa "struct addrinfo **restrict res"
44 function is used to get a list of
46 addresses and port numbers for host
50 It is a replacement for and provides more flexibility than the
60 arguments are either pointers to NUL-terminated strings or the null pointer.
61 An acceptable value for
63 is either a valid host name or a numeric host address string consisting
64 of a dotted decimal IPv4 address or an IPv6 address.
67 is either a decimal port number or a service name listed in
76 is an optional pointer to a
82 int ai_flags; /* input flags */
83 int ai_family; /* protocol family for socket */
84 int ai_socktype; /* socket type */
85 int ai_protocol; /* protocol for socket */
86 socklen_t ai_addrlen; /* length of socket-address */
87 struct sockaddr *ai_addr; /* socket-address for socket */
88 char *ai_canonname; /* canonical name for service location */
89 struct addrinfo *ai_next; /* pointer to next in list */
93 This structure can be used to provide hints concerning the type of socket
94 that the caller supports or wishes to use.
95 The caller can supply the following structure elements in
97 .Bl -tag -width "ai_socktypeXX"
99 The protocol family that should be used.
104 it means the caller will accept any protocol family supported by the
107 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,
122 is zero the caller will accept any protocol.
127 the following values:
128 .Bl -tag -width "AI_CANONNAMEXX"
132 bit is set, a successful call to
134 will return a NUL-terminated string containing the canonical name
135 of the specified hostname in the
140 .It Dv AI_NUMERICHOST
143 bit is set, it indicates that
145 should be treated as a numeric string defining an IPv4 or IPv6 address
146 and no name resolution should be attempted.
150 bit is set it indicates that the returned socket address structure
151 is intended for use in a call to
155 argument is the null pointer, then the IP address portion of the
156 socket address structure will be set to
158 for an IPv4 address or
164 bit is not set, the returned socket address structure will be ready
167 for a connection-oriented protocol or
172 if a connectionless protocol was chosen.
175 address portion of the socket address structure will be set to the
178 is the null pointer and
184 All other elements of the
188 must be zero or the null pointer.
194 behaves as if the caller provided a
200 and all other elements set to zero or
203 After a successful call to
206 is a pointer to a linked list of one or more
209 The list can be traversed by following the
213 structure until a null pointer is encountered.
221 structure are suitable for a call to
225 structure in the list, the
227 member points to a filled-in socket address structure of length
230 This implementation of
232 allows numeric IPv6 address notation with scope identifier,
233 as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
234 By appending the percent character and scope identifier to addresses,
238 This would make management of scoped addresses easier
239 and allows cut-and-paste input of scoped addresses.
241 At this moment the code supports only link-local addresses with the format.
242 The scope identifier is hardcoded to the name of the hardware interface
254 on the link associated with the
259 The current implementation assumes a one-to-one relationship between
260 the interface and link, which is not necessarily true from the specification.
262 All of the information returned by
264 is dynamically allocated: the
266 structures themselves as well as the socket address structures and
267 the canonical host name strings included in the
271 Memory allocated for the dynamically allocated structures created by
281 structure created by a call to
285 returns zero on success or one of the error codes listed in
289 The following code tries to connect to
294 It loops through all the addresses available, regardless of address family.
295 If the destination resolves to an IPv4 address, it will use an
298 Similarly, if it resolves to IPv6, an
301 Observe that there is no hardcoded reference to a particular address family.
302 The code works even if
304 returns addresses that are not IPv4/v6.
305 .Bd -literal -offset indent
306 struct addrinfo hints, *res, *res0;
309 const char *cause = NULL;
311 memset(&hints, 0, sizeof(hints));
312 hints.ai_family = PF_UNSPEC;
313 hints.ai_socktype = SOCK_STREAM;
314 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
316 errx(1, "%s", gai_strerror(error));
320 for (res = res0; res; res = res->ai_next) {
321 s = socket(res->ai_family, res->ai_socktype,
328 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
335 break; /* okay we got one */
344 The following example tries to open a wildcard listening socket onto service
346 for all the address families available.
347 .Bd -literal -offset indent
348 struct addrinfo hints, *res, *res0;
352 const char *cause = NULL;
354 memset(&hints, 0, sizeof(hints));
355 hints.ai_family = PF_UNSPEC;
356 hints.ai_socktype = SOCK_STREAM;
357 hints.ai_flags = AI_PASSIVE;
358 error = getaddrinfo(NULL, "http", &hints, &res0);
360 errx(1, "%s", gai_strerror(error));
364 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
365 s[nsock] = socket(res->ai_family, res->ai_socktype,
372 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
377 (void) listen(s[nsock], 5);
388 .Fd #include <sys/types.h>
389 .Fd #include <sys/socket.h>
390 .Fd #include <netdb.h>
401 .Xr gethostbyname 3 ,
403 .Xr getservbyname 3 ,
416 .%T Basic Socket Interface Extensions for IPv6
426 .%T "IPv6 Scoped Address Architecture"
428 .%N draft-ietf-ipv6-scoping-arch-02.txt
429 .%O work in progress material
433 .%T Protocol Independence Using the Sockets API
434 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
440 function is defined by the
442 draft specification and documented in
444 .Dq Basic Socket Interface Extensions for IPv6 .