1FREEADDRINFO(3P) POSIX Programmer's Manual FREEADDRINFO(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 freeaddrinfo, getaddrinfo — get address information
14
16 #include <sys/socket.h>
17 #include <netdb.h>
18 void freeaddrinfo(struct addrinfo *ai);
20 int getaddrinfo(const char *restrict nodename,
21 const char *restrict servname,
22 const struct addrinfo *restrict hints,
23 struct addrinfo **restrict res);
24
26 The freeaddrinfo() function shall free one or more addrinfo structures
27 returned by getaddrinfo(), along with any additional storage associated
28 with those structures. If the ai_next field of the structure is not
29 null, the entire list of structures shall be freed. The freeaddrinfo()
30 function shall support the freeing of arbitrary sublists of an addrinfo
31 list originally returned by getaddrinfo().
32 The getaddrinfo() function shall translate the name of a service loca‐
34 tion (for example, a host name) and/or a service name and shall return
35 a set of socket addresses and associated information to be used in cre‐
36 ating a socket with which to address the specified service.
37 Note: In many cases it is implemented by the Domain Name System, as
39 documented in RFC 1034, RFC 1035, and RFC 1886.
40 The freeaddrinfo() and getaddrinfo() functions shall be thread-safe.
42 The nodename and servname arguments are either null pointers or point‐
44 ers to null-terminated strings. One or both of these two arguments
45 shall be supplied by the application as a non-null pointer.
46 The format of a valid name depends on the address family or families.
48 If a specific family is not given and the name could be interpreted as
49 valid within multiple supported families, the implementation shall
50 attempt to resolve the name in all supported families and, in absence
51 of errors, one or more results shall be returned.
52 If the nodename argument is not null, it can be a descriptive name or
54 can be an address string. If the specified address family is AF_INET,
55 AF_INET6, or AF_UNSPEC, valid descriptive names include host names. If
56 the specified address family is AF_INET or AF_UNSPEC, address strings
57 using Internet standard dot notation as specified in inet_addr() are
58 valid.
59 If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
61 text forms described in inet_ntop() are valid.
62 If nodename is not null, the requested service location is named by
64 nodename; otherwise, the requested service location is local to the
65 caller.
66 If servname is null, the call shall return network-level addresses for
68 the specified nodename. If servname is not null, it is a null-termi‐
69 nated character string identifying the requested service. This can be
70 either a descriptive name or a numeric representation suitable for use
71 with the address family or families. If the specified address family
72 is AF_INET, AF_INET6, or AF_UNSPEC, the service can be specified as a
73 string specifying a decimal port number.
74 If the hints argument is not null, it refers to a structure containing
76 input values that directs the operation by providing options and by
77 limiting the returned information to a specific socket type, address
78 family, and/or protocol, as described below. In this hints structure
79 every member other than ai_flags, ai_family, ai_socktype, and ai_proto‐
80 col shall be set to zero or a null pointer. A value of AF_UNSPEC for
81 ai_family means that the caller shall accept any address family. A
82 value of zero for ai_socktype means that the caller shall accept any
83 socket type. A value of zero for ai_protocol means that the caller
84 shall accept any protocol. If hints is a null pointer, the behavior
85 shall be as if it referred to a structure containing the value zero for
86 the ai_flags, ai_socktype, and ai_protocol fields, and AF_UNSPEC for
87 the ai_family field.
88 The ai_flags field to which the hints parameter points shall be set to
90 zero or be the bitwise-inclusive OR of one or more of the values
91 AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED,
92 AI_ALL, and AI_ADDRCONFIG.
93 If the AI_PASSIVE flag is specified, the returned address information
95 shall be suitable for use in binding a socket for accepting incoming
96 connections for the specified service. In this case, if the nodename
97 argument is null, then the IP address portion of the socket address
98 structure shall be set to INADDR_ANY for an IPv4 address or
99 IN6ADDR_ANY_INIT for an IPv6 address. If the AI_PASSIVE flag is not
100 specified, the returned address information shall be suitable for a
101 call to connect() (for a connection-mode protocol) or for a call to
102 connect(), sendto(), or sendmsg() (for a connectionless protocol). In
103 this case, if the nodename argument is null, then the IP address por‐
104 tion of the socket address structure shall be set to the loopback
105 address. The AI_PASSIVE flag shall be ignored if the nodename argument
106 is not null.
107 If the AI_CANONNAME flag is specified and the nodename argument is not
109 null, the function shall attempt to determine the canonical name corre‐
110 sponding to nodename (for example, if nodename is an alias or shorthand
111 notation for a complete name).
112 Note: Since different implementations use different conceptual mod‐
114 els, the terms ``canonical name'' and ``alias'' cannot be
115 precisely defined for the general case. However, Domain Name
116 System implementations are expected to interpret them as they
117 are used in RFC 1034.
118 A numeric host address string is not a ``name'', and thus
120 does not have a ``canonical name'' form; no address to host
121 name translation is performed. See below for handling of the
122 case where a canonical name cannot be obtained.
123 If the AI_NUMERICHOST flag is specified, then a non-null nodename
125 string supplied shall be a numeric host address string. Otherwise, an
126 [EAI_NONAME] error is returned. This flag shall prevent any type of
127 name resolution service (for example, the DNS) from being invoked.
128 If the AI_NUMERICSERV flag is specified, then a non-null servname
130 string supplied shall be a numeric port string. Otherwise, an [EAI_NO‐
131 NAME] error shall be returned. This flag shall prevent any type of name
132 resolution service (for example, NIS+) from being invoked.
133 If the AI_V4MAPPED flag is specified along with an ai_family of
135 AF_INET6, then getaddrinfo() shall return IPv4-mapped IPv6 addresses on
136 finding no matching IPv6 addresses (ai_addrlen shall be 16). The
137 AI_V4MAPPED flag shall be ignored unless ai_family equals AF_INET6. If
138 the AI_ALL flag is used with the AI_V4MAPPED flag, then getaddrinfo()
139 shall return all matching IPv6 and IPv4 addresses. The AI_ALL flag
140 without the AI_V4MAPPED flag is ignored.
141 If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be
143 returned only if an IPv4 address is configured on the local system, and
144 IPv6 addresses shall be returned only if an IPv6 address is configured
145 on the local system.
146 The ai_socktype field to which argument hints points specifies the
148 socket type for the service, as defined in socket(). If a specific
149 socket type is not given (for example, a value of zero) and the service
150 name could be interpreted as valid with multiple supported socket
151 types, the implementation shall attempt to resolve the service name for
152 all supported socket types and, in the absence of errors, all possible
153 results shall be returned. A non-zero socket type value shall limit the
154 returned information to values with the specified socket type.
155 If the ai_family field to which hints points has the value AF_UNSPEC,
157 addresses shall be returned for use with any address family that can be
158 used with the specified nodename and/or servname. Otherwise, addresses
159 shall be returned for use only with the specified address family. If
160 ai_family is not AF_UNSPEC and ai_protocol is not zero, then addresses
161 shall be returned for use only with the specified address family and
162 protocol; the value of ai_protocol shall be interpreted as in a call to
163 the socket() function with the corresponding values of ai_family and
164 ai_protocol.
165
167 A zero return value for getaddrinfo() indicates successful completion;
168 a non-zero return value indicates failure. The possible values for the
169 failures are listed in the ERRORS section.
170 Upon successful return of getaddrinfo(), the location to which res
172 points shall refer to a linked list of addrinfo structures, each of
173 which shall specify a socket address and information for use in creat‐
174 ing a socket with which to use that socket address. The list shall
175 include at least one addrinfo structure. The ai_next field of each
176 structure contains a pointer to the next structure on the list, or a
177 null pointer if it is the last structure on the list. Each structure on
178 the list shall include values for use with a call to the socket() func‐
179 tion, and a socket address for use with the connect() function or, if
180 the AI_PASSIVE flag was specified, for use with the bind() function.
181 The fields ai_family, ai_socktype, and ai_protocol shall be usable as
182 the arguments to the socket() function to create a socket suitable for
183 use with the returned address. The fields ai_addr and ai_addrlen are
184 usable as the arguments to the connect() or bind() functions with such
185 a socket, according to the AI_PASSIVE flag.
186 If nodename is not null, and if requested by the AI_CANONNAME flag, the
188 ai_canonname field of the first returned addrinfo structure shall point
189 to a null-terminated string containing the canonical name corresponding
190 to the input nodename; if the canonical name is not available, then
191 ai_canonname shall refer to the nodename argument or a string with the
192 same contents. The contents of the ai_flags field of the returned
193 structures are undefined.
194 All fields in socket address structures returned by getaddrinfo() that
196 are not filled in through an explicit argument (for example, sin6_flow‐
197 info) shall be set to zero.
198 Note: This makes it easier to compare socket address structures.
200
202 The getaddrinfo() function shall fail and return the corresponding
203 error value if:
204 [EAI_AGAIN] The name could not be resolved at this time. Future
206 attempts may succeed.
207 [EAI_BADFLAGS]
209 The flags parameter had an invalid value.
210 [EAI_FAIL] A non-recoverable error occurred when attempting to resolve
212 the name.
213 [EAI_FAMILY]
215 The address family was not recognized.
216 [EAI_MEMORY]
218 There was a memory allocation failure when trying to allo‐
219 cate storage for the return value.
220 [EAI_NONAME]
222 The name does not resolve for the supplied parameters.
223 Neither nodename nor servname were supplied. At least one
225 of these shall be supplied.
226 [EAI_SERVICE]
228 The service passed was not recognized for the specified
229 socket type.
230 [EAI_SOCKTYPE]
232 The intended socket type was not recognized.
233 [EAI_SYSTEM]
235 A system error occurred; the error code can be found in
236 errno.
237 The following sections are informative.
239
241 The following (incomplete) program demonstrates the use of getad‐
242 drinfo() to obtain the socket address structure(s) for the service
243 named in the program's command-line argument. The program then loops
244 through each of the address structures attempting to create and bind a
245 socket to the address, until it performs a successful bind().
246 #include <stdio.h>
248 #include <stdlib.h>
249 #include <unistd.h>
250 #include <string.h>
251 #include <sys/socket.h>
252 #include <netdb.h>
253 int
255 main(int argc, char *argv[])
256 {
257 struct addrinfo *result, *rp;
258 int sfd, s;
259 if (argc != 2) {
261 fprintf(stderr, "Usage: %s port\n", argv[0]);
262 exit(EXIT_FAILURE);
263 }
264 struct addrinfo hints = {};
266 hints.ai_family = AF_UNSPEC;
267 hints.ai_socktype = SOCK_DGRAM;
268 hints.ai_flags = AI_PASSIVE;
269 hints.ai_protocol = 0;
270 s = getaddrinfo(NULL, argv[1], &hints, &result);
272 if (s != 0) {
273 fprintf(stderr, "getaddrinfo: %s\n", gai_strerror(s));
274 exit(EXIT_FAILURE);
275 }
276 /* getaddrinfo() returns a list of address structures.
278 Try each address until a successful bind().
279 If socket(2) (or bind(2)) fails, close the socket
280 and try the next address. */
281 for (rp = result; rp != NULL; rp = rp->ai_next) {
283 sfd = socket(rp->ai_family, rp->ai_socktype,
284 rp->ai_protocol);
285 if (sfd == -1)
286 continue;
287 if (bind(sfd, rp->ai_addr, rp->ai_addrlen) == 0)
289 break; /* Success */
290 close(sfd);
292 }
293 if (rp == NULL) { /* No address succeeded */
295 fprintf(stderr, "Could not bind\n");
296 exit(EXIT_FAILURE);
297 }
298 freeaddrinfo(result); /* No longer needed */
300 /* ... use socket bound to sfd ... */
302 }
303
305 If the caller handles only TCP and not UDP, for example, then the
306 ai_protocol member of the hints structure should be set to IPPROTO_TCP
307 when getaddrinfo() is called.
308 If the caller handles only IPv4 and not IPv6, then the ai_family member
310 of the hints structure should be set to AF_INET when getaddrinfo() is
311 called.
312 The term ``canonical name'' is misleading; it is taken from the Domain
314 Name System (RFC 2181). It should be noted that the canonical name is a
315 result of alias processing, and not necessarily a unique attribute of a
316 host, address, or set of addresses. See RFC 2181 for more discussion of
317 this in the Domain Name System context.
318
320 None.
321
323 None.
324
326 connect(), endservent(), gai_strerror(), getnameinfo(), socket()
327 The Base Definitions volume of POSIX.1‐2008, <netdb.h>, <sys_socket.h>
329
331 Portions of this text are reprinted and reproduced in electronic form
332 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
333 -- Portable Operating System Interface (POSIX), The Open Group Base
334 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
335 cal and Electronics Engineers, Inc and The Open Group. (This is
336 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
337 event of any discrepancy between this version and the original IEEE and
338 The Open Group Standard, the original IEEE and The Open Group Standard
339 is the referee document. The original Standard can be obtained online
340 at http://www.unix.org/online.html .
341 Any typographical or formatting errors that appear in this page are
343 most likely to have been introduced during the conversion of the source
344 files to man page format. To report such errors, see https://www.ker‐
345 nel.org/doc/man-pages/reporting_bugs.html .
346IEEE/The Open Group 2013 FREEADDRINFO(3P)