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
12 freeaddrinfo, getaddrinfo — get address information
13
15 #include <sys/socket.h>
16 #include <netdb.h>
17 void freeaddrinfo(struct addrinfo *ai);
19 int getaddrinfo(const char *restrict nodename,
20 const char *restrict servname,
21 const struct addrinfo *restrict hints,
22 struct addrinfo **restrict res);
23
25 The freeaddrinfo() function shall free one or more addrinfo structures
26 returned by getaddrinfo(), along with any additional storage associated
27 with those structures. If the ai_next field of the structure is not
28 null, the entire list of structures shall be freed. The freeaddrinfo()
29 function shall support the freeing of arbitrary sublists of an addrinfo
30 list originally returned by getaddrinfo().
31 The getaddrinfo() function shall translate the name of a service loca‐
33 tion (for example, a host name) and/or a service name and shall return
34 a set of socket addresses and associated information to be used in cre‐
35 ating a socket with which to address the specified service.
36 Note: In many cases it is implemented by the Domain Name System, as
38 documented in RFC 1034, RFC 1035, and RFC 1886.
39 The freeaddrinfo() and getaddrinfo() functions shall be thread-safe.
41 The nodename and servname arguments are either null pointers or point‐
43 ers to null-terminated strings. One or both of these two arguments
44 shall be supplied by the application as a non-null pointer.
45 The format of a valid name depends on the address family or families.
47 If a specific family is not given and the name could be interpreted as
48 valid within multiple supported families, the implementation shall
49 attempt to resolve the name in all supported families and, in absence
50 of errors, one or more results shall be returned.
51 If the nodename argument is not null, it can be a descriptive name or
53 can be an address string. If the specified address family is AF_INET,
54 AF_INET6, or AF_UNSPEC, valid descriptive names include host names. If
55 the specified address family is AF_INET or AF_UNSPEC, address strings
56 using Internet standard dot notation as specified in inet_addr() are
57 valid.
58 If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
60 text forms described in inet_ntop() are valid.
61 If nodename is not null, the requested service location is named by
63 nodename; otherwise, the requested service location is local to the
64 caller.
65 If servname is null, the call shall return network-level addresses for
67 the specified nodename. If servname is not null, it is a null-termi‐
68 nated character string identifying the requested service. This can be
69 either a descriptive name or a numeric representation suitable for use
70 with the address family or families. If the specified address family
71 is AF_INET, AF_INET6, or AF_UNSPEC, the service can be specified as a
72 string specifying a decimal port number.
73 If the hints argument is not null, it refers to a structure containing
75 input values that directs the operation by providing options and by
76 limiting the returned information to a specific socket type, address
77 family, and/or protocol, as described below. The application shall
78 ensure that each of the ai_addrlen, ai_addr, ai_canonname, and ai_next
79 members, as well as each of the non-standard additional members, if
80 any, of this hints structure is initialized. If any of these members
81 has a value other than the value that would result from default ini‐
82 tialization, the behavior is implementation-defined. A value of
83 AF_UNSPEC for ai_family means that the caller shall accept any address
84 family. A value of zero for ai_socktype means that the caller shall
85 accept any socket type. A value of zero for ai_protocol means that the
86 caller shall accept any protocol. If hints is a null pointer, the
87 behavior shall be as if it referred to a structure containing the value
88 zero for the ai_flags, ai_socktype, and ai_protocol fields, and
89 AF_UNSPEC for the ai_family field.
90 The ai_flags field to which the hints parameter points shall be set to
92 zero or be the bitwise-inclusive OR of one or more of the values
93 AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED,
94 AI_ALL, and AI_ADDRCONFIG.
95 If the AI_PASSIVE flag is specified, the returned address information
97 shall be suitable for use in binding a socket for accepting incoming
98 connections for the specified service. In this case, if the nodename
99 argument is null, then the IP address portion of the socket address
100 structure shall be set to INADDR_ANY for an IPv4 address or
101 IN6ADDR_ANY_INIT for an IPv6 address. If the AI_PASSIVE flag is not
102 specified, the returned address information shall be suitable for a
103 call to connect() (for a connection-mode protocol) or for a call to
104 connect(), sendto(), or sendmsg() (for a connectionless protocol). In
105 this case, if the nodename argument is null, then the IP address por‐
106 tion of the socket address structure shall be set to the loopback
107 address. The AI_PASSIVE flag shall be ignored if the nodename argument
108 is not null.
109 If the AI_CANONNAME flag is specified and the nodename argument is not
111 null, the function shall attempt to determine the canonical name corre‐
112 sponding to nodename (for example, if nodename is an alias or shorthand
113 notation for a complete name).
114 Note: Since different implementations use different conceptual mod‐
116 els, the terms ``canonical name'' and ``alias'' cannot be
117 precisely defined for the general case. However, Domain Name
118 System implementations are expected to interpret them as they
119 are used in RFC 1034.
120 A numeric host address string is not a ``name'', and thus
122 does not have a ``canonical name'' form; no address to host
123 name translation is performed. See below for handling of the
124 case where a canonical name cannot be obtained.
125 If the AI_NUMERICHOST flag is specified, then a non-null nodename
127 string supplied shall be a numeric host address string. Otherwise, an
128 [EAI_NONAME] error is returned. This flag shall prevent any type of
129 name resolution service (for example, the DNS) from being invoked.
130 If the AI_NUMERICSERV flag is specified, then a non-null servname
132 string supplied shall be a numeric port string. Otherwise, an [EAI_NO‐
133 NAME] error shall be returned. This flag shall prevent any type of name
134 resolution service (for example, NIS+) from being invoked.
135 By default, with an ai_family of AF_INET6, getaddrinfo() shall return
137 only IPv6 addresses. If the AI_V4MAPPED flag is specified along with an
138 ai_family of AF_INET6, then getaddrinfo() shall return IPv4-mapped IPv6
139 addresses on finding no matching IPv6 addresses. The AI_V4MAPPED flag
140 shall be ignored unless ai_family equals AF_INET6. If the AI_ALL flag
141 is used with the AI_V4MAPPED flag, then getaddrinfo() shall return all
142 matching IPv6 and IPv4 addresses. The AI_ALL flag without the
143 AI_V4MAPPED flag shall be ignored.
144 If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be
146 returned only if an IPv4 address is configured on the local system, and
147 IPv6 addresses shall be returned only if an IPv6 address is configured
148 on the local system.
149 The ai_socktype field to which argument hints points specifies the
151 socket type for the service, as defined in socket(). If a specific
152 socket type is not given (for example, a value of zero) and the service
153 name could be interpreted as valid with multiple supported socket
154 types, the implementation shall attempt to resolve the service name for
155 all supported socket types and, in the absence of errors, all possible
156 results shall be returned. A non-zero socket type value shall limit the
157 returned information to values with the specified socket type.
158 If the ai_family field to which hints points has the value AF_UNSPEC,
160 addresses shall be returned for use with any address family that can be
161 used with the specified nodename and/or servname. Otherwise, addresses
162 shall be returned for use only with the specified address family. If
163 ai_family is not AF_UNSPEC and ai_protocol is not zero, then addresses
164 shall be returned for use only with the specified address family and
165 protocol; the value of ai_protocol shall be interpreted as in a call to
166 the socket() function with the corresponding values of ai_family and
167 ai_protocol.
168
170 A zero return value for getaddrinfo() indicates successful completion;
171 a non-zero return value indicates failure. The possible values for the
172 failures are listed in the ERRORS section.
173 Upon successful return of getaddrinfo(), the location to which res
175 points shall refer to a linked list of addrinfo structures, each of
176 which shall specify a socket address and information for use in creat‐
177 ing a socket with which to use that socket address. The list shall
178 include at least one addrinfo structure. The ai_next field of each
179 structure contains a pointer to the next structure on the list, or a
180 null pointer if it is the last structure on the list. Each structure on
181 the list shall include values for use with a call to the socket() func‐
182 tion, and a socket address for use with the connect() function or, if
183 the AI_PASSIVE flag was specified, for use with the bind() function.
184 The fields ai_family, ai_socktype, and ai_protocol shall be usable as
185 the arguments to the socket() function to create a socket suitable for
186 use with the returned address. The fields ai_addr and ai_addrlen are
187 usable as the arguments to the connect() or bind() functions with such
188 a socket, according to the AI_PASSIVE flag.
189 If nodename is not null, and if requested by the AI_CANONNAME flag, the
191 ai_canonname field of the first returned addrinfo structure shall point
192 to a null-terminated string containing the canonical name corresponding
193 to the input nodename; if the canonical name is not available, then
194 ai_canonname shall refer to the nodename argument or a string with the
195 same contents. The contents of the ai_flags field of the returned
196 structures are undefined.
197 All fields in socket address structures returned by getaddrinfo() that
199 are not filled in through an explicit argument (for example, sin6_flow‐
200 info) shall be set to zero.
201 Note: This makes it easier to compare socket address structures.
203
205 The getaddrinfo() function shall fail and return the corresponding
206 error value if:
207 [EAI_AGAIN] The name could not be resolved at this time. Future
209 attempts may succeed.
210 [EAI_BADFLAGS]
212 The flags parameter had an invalid value.
213 [EAI_FAIL] A non-recoverable error occurred when attempting to resolve
215 the name.
216 [EAI_FAMILY]
218 The address family was not recognized.
219 [EAI_MEMORY]
221 There was a memory allocation failure when trying to allo‐
222 cate storage for the return value.
223 [EAI_NONAME]
225 The name does not resolve for the supplied parameters.
226 Neither nodename nor servname were supplied. At least one
228 of these shall be supplied.
229 [EAI_SERVICE]
231 The service passed was not recognized for the specified
232 socket type.
233 [EAI_SOCKTYPE]
235 The intended socket type was not recognized.
236 [EAI_SYSTEM]
238 A system error occurred; the error code can be found in
239 errno.
240 The following sections are informative.
242
244 The following (incomplete) program demonstrates the use of getad‐
245 drinfo() to obtain the socket address structure(s) for the service
246 named in the program's command-line argument. The program then loops
247 through each of the address structures attempting to create and bind a
248 socket to the address, until it performs a successful bind().
249 #include <stdio.h>
252 #include <stdlib.h>
253 #include <unistd.h>
254 #include <string.h>
255 #include <sys/socket.h>
256 #include <netdb.h>
257 int
259 main(int argc, char *argv[])
260 {
261 struct addrinfo *result, *rp;
262 int sfd, s;
263 if (argc != 2) {
265 fprintf(stderr, "Usage: %s port\n", argv[0]);
266 exit(EXIT_FAILURE);
267 }
268 struct addrinfo hints = {0};
270 hints.ai_family = AF_UNSPEC;
271 hints.ai_socktype = SOCK_DGRAM;
272 hints.ai_flags = AI_PASSIVE;
273 hints.ai_protocol = 0;
274 s = getaddrinfo(NULL, argv[1], &hints, &result);
276 if (s != 0) {
277 fprintf(stderr, "getaddrinfo: %s\n", gai_strerror(s));
278 exit(EXIT_FAILURE);
279 }
280 /* getaddrinfo() returns a list of address structures.
282 Try each address until a successful bind().
283 If socket(2) (or bind(2)) fails, close the socket
284 and try the next address. */
285 for (rp = result; rp != NULL; rp = rp->ai_next) {
287 sfd = socket(rp->ai_family, rp->ai_socktype,
288 rp->ai_protocol);
289 if (sfd == -1)
290 continue;
291 if (bind(sfd, rp->ai_addr, rp->ai_addrlen) == 0)
293 break; /* Success */
294 close(sfd);
296 }
297 if (rp == NULL) { /* No address succeeded */
299 fprintf(stderr, "Could not bind\n");
300 exit(EXIT_FAILURE);
301 }
302 freeaddrinfo(result); /* No longer needed */
304 /* ... use socket bound to sfd ... */
306 }
307
309 If the caller handles only TCP and not UDP, for example, then the
310 ai_protocol member of the hints structure should be set to IPPROTO_TCP
311 when getaddrinfo() is called.
312 If the caller handles only IPv4 and not IPv6, then the ai_family member
314 of the hints structure should be set to AF_INET when getaddrinfo() is
315 called.
316 Although it is common practice to initialize the hints structure using:
318 struct addrinfo hints;
321 memset(&hints, 0, sizeof hints);
322 this method is not portable according to this standard, because the
324 structure can contain pointer or floating-point members that are not
325 required to have an all-bits-zero representation after default initial‐
326 ization. Portable methods make use of default initialization; for exam‐
327 ple:
328 struct addrinfo hints = { 0 };
331 or:
333 static struct addrinfo hints_init;
336 struct addrinfo hints = hints_init;
337 A future version of this standard may require that a pointer object
339 with an all-bits-zero representation is a null pointer, and that
340 addrinfo does not have any floating-point members if a floating-point
341 object with an all-bits-zero representation does not have the value
342 0.0.
343 The term ``canonical name'' is misleading; it is taken from the Domain
345 Name System (RFC 2181). It should be noted that the canonical name is a
346 result of alias processing, and not necessarily a unique attribute of a
347 host, address, or set of addresses. See RFC 2181 for more discussion of
348 this in the Domain Name System context.
349
351 None.
352
354 None.
355
357 connect(), endservent(), gai_strerror(), getnameinfo(), socket()
358 The Base Definitions volume of POSIX.1‐2017, <netdb.h>, <sys_socket.h>
360
362 Portions of this text are reprinted and reproduced in electronic form
363 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
364 table Operating System Interface (POSIX), The Open Group Base Specifi‐
365 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
366 Electrical and Electronics Engineers, Inc and The Open Group. In the
367 event of any discrepancy between this version and the original IEEE and
368 The Open Group Standard, the original IEEE and The Open Group Standard
369 is the referee document. The original Standard can be obtained online
370 at http://www.opengroup.org/unix/online.html .
371 Any typographical or formatting errors that appear in this page are
373 most likely to have been introduced during the conversion of the source
374 files to man page format. To report such errors, see https://www.ker‐
375 nel.org/doc/man-pages/reporting_bugs.html .
376IEEE/The Open Group 2017 FREEADDRINFO(3P)