1FREEADDRINFO(P) POSIX Programmer's Manual FREEADDRINFO(P)
2
6 freeaddrinfo, getaddrinfo - get address information
7
9 #include <sys/socket.h>
10 #include <netdb.h>
11 void freeaddrinfo(struct addrinfo *ai);
13 int getaddrinfo(const char *restrict nodename,
14 const char *restrict servname,
15 const struct addrinfo *restrict hints,
16 struct addrinfo **restrict res);
17
20 The freeaddrinfo() function shall free one or more addrinfo structures
21 returned by getaddrinfo(), along with any additional storage associated
22 with those structures. If the ai_next field of the structure is not
23 null, the entire list of structures shall be freed. The freeaddrinfo()
24 function shall support the freeing of arbitrary sublists of an addrinfo
25 list originally returned by getaddrinfo().
26 The getaddrinfo() function shall translate the name of a service loca‐
28 tion (for example, a host name) and/or a service name and shall return
29 a set of socket addresses and associated information to be used in cre‐
30 ating a socket with which to address the specified service.
31 Note: In many cases it is implemented by the Domain Name System, as
33 documented in RFC 1034, RFC 1035, and RFC 1886.
34 The freeaddrinfo() and getaddrinfo() functions shall be thread-safe.
37 The nodename and servname arguments are either null pointers or point‐
39 ers to null-terminated strings. One or both of these two arguments
40 shall be supplied by the application as a non-null pointer.
41 The format of a valid name depends on the address family or families.
43 If a specific family is not given and the name could be interpreted as
44 valid within multiple supported families, the implementation shall
45 attempt to resolve the name in all supported families and, in absence
46 of errors, one or more results shall be returned.
47 If the nodename argument is not null, it can be a descriptive name or
49 can be an address string. If the specified address family is AF_INET,
50 AF_INET6, or AF_UNSPEC, valid descriptive names include host names.
51 If the specified address family is AF_INET or AF_UNSPEC, address
52 strings using Internet standard dot notation as specified in
53 inet_addr() are valid.
54 If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
56 text forms described in inet_ntop() are valid.
57 If nodename is not null, the requested service location is named by
59 nodename; otherwise, the requested service location is local to the
60 caller.
61 If servname is null, the call shall return network-level addresses for
63 the specified nodename. If servname is not null, it is a null-termi‐
64 nated character string identifying the requested service. This can be
65 either a descriptive name or a numeric representation suitable for use
66 with the address family or families. If the specified address family is
67 AF_INET, AF_INET6, or AF_UNSPEC, the service can be specified as a
68 string specifying a decimal port number.
69 If the hints argument is not null, it refers to a structure containing
71 input values that may direct the operation by providing options and by
72 limiting the returned information to a specific socket type, address
73 family, and/or protocol. In this hints structure every member other
74 than ai_flags, ai_family, ai_socktype, and ai_protocol shall be set to
75 zero or a null pointer. A value of AF_UNSPEC for ai_family means that
76 the caller shall accept any address family. A value of zero for
77 ai_socktype means that the caller shall accept any socket type. A value
78 of zero for ai_protocol means that the caller shall accept any proto‐
79 col. If hints is a null pointer, the behavior shall be as if it
80 referred to a structure containing the value zero for the ai_flags,
81 ai_socktype, and ai_protocol fields, and AF_UNSPEC for the ai_family
82 field.
83 The ai_flags field to which the hints parameter points shall be set to
85 zero or be the bitwise-inclusive OR of one or more of the values
86 AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED,
87 AI_ALL, and AI_ADDRCONFIG.
88 If the AI_PASSIVE flag is specified, the returned address information
90 shall be suitable for use in binding a socket for accepting incoming
91 connections for the specified service. In this case, if the nodename
92 argument is null, then the IP address portion of the socket address
93 structure shall be set to INADDR_ANY for an IPv4 address or
94 IN6ADDR_ANY_INIT for an IPv6 address. If the AI_PASSIVE flag is not
95 specified, the returned address information shall be suitable for a
96 call to connect() (for a connection-mode protocol) or for a call to
97 connect(), sendto(), or sendmsg() (for a connectionless protocol). In
98 this case, if the nodename argument is null, then the IP address por‐
99 tion of the socket address structure shall be set to the loopback
100 address. The AI_PASSIVE flag shall be ignored if the nodename argument
101 is not null.
102 If the AI_CANONNAME flag is specified and the nodename argument is not
104 null, the function shall attempt to determine the canonical name corre‐
105 sponding to nodename (for example, if nodename is an alias or shorthand
106 notation for a complete name).
107 Note: Since different implementations use different conceptual models,
109 the terms ``canonical name'' and ``alias'' cannot be precisely
110 defined for the general case. However, Domain Name System imple‐
111 mentations are expected to interpret them as they are used in
112 RFC 1034.
113 A numeric host address string is not a ``name'', and thus does not have
115 a ``canonical name'' form; no address to host name translation is per‐
116 formed. See below for handling of the case where a canonical name can‐
117 not be obtained.
118 If the AI_NUMERICHOST flag is specified, then a non-null nodename
121 string supplied shall be a numeric host address string. Otherwise, an
122 [EAI_NONAME] error is returned. This flag shall prevent any type of
123 name resolution service (for example, the DNS) from being invoked.
124 If the AI_NUMERICSERV flag is specified, then a non-null servname
126 string supplied shall be a numeric port string. Otherwise, an [EAI_NO‐
127 NAME] error shall be returned. This flag shall prevent any type of name
128 resolution service (for example, NIS+) from being invoked.
129 If the AI_V4MAPPED flag is specified along with an ai_family of
131 AF_INET6, then getaddrinfo() shall return IPv4-mapped IPv6 addresses on
132 finding no matching IPv6 addresses ( ai_addrlen shall be 16). The
133 AI_V4MAPPED flag shall be ignored unless ai_family equals AF_INET6. If
134 the AI_ALL flag is used with the AI_V4MAPPED flag, then getaddrinfo()
135 shall return all matching IPv6 and IPv4 addresses. The AI_ALL flag
136 without the AI_V4MAPPED flag is ignored.
137 If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be
139 returned only if an IPv4 address is configured on the local system,
140 and IPv6 addresses shall be returned only if an IPv6 address is con‐
141 figured on the local system.
142 The ai_socktype field to which argument hints points specifies the
144 socket type for the service, as defined in socket() . If a specific
145 socket type is not given (for example, a value of zero) and the service
146 name could be interpreted as valid with multiple supported socket
147 types, the implementation shall attempt to resolve the service name for
148 all supported socket types and, in the absence of errors, all possible
149 results shall be returned. A non-zero socket type value shall limit the
150 returned information to values with the specified socket type.
151 If the ai_family field to which hints points has the value AF_UNSPEC,
153 addresses shall be returned for use with any address family that can be
154 used with the specified nodename and/or servname. Otherwise, addresses
155 shall be returned for use only with the specified address family. If
156 ai_family is not AF_UNSPEC and ai_protocol is not zero, then addresses
157 are returned for use only with the specified address family and proto‐
158 col; the value of ai_protocol shall be interpreted as in a call to the
159 socket() function with the corresponding values of ai_family and
160 ai_protocol.
161
163 A zero return value for getaddrinfo() indicates successful completion;
164 a non-zero return value indicates failure. The possible values for the
165 failures are listed in the ERRORS section.
166 Upon successful return of getaddrinfo(), the location to which res
168 points shall refer to a linked list of addrinfo structures, each of
169 which shall specify a socket address and information for use in creat‐
170 ing a socket with which to use that socket address. The list shall
171 include at least one addrinfo structure. The ai_next field of each
172 structure contains a pointer to the next structure on the list, or a
173 null pointer if it is the last structure on the list. Each structure on
174 the list shall include values for use with a call to the socket() func‐
175 tion, and a socket address for use with the connect() function or, if
176 the AI_PASSIVE flag was specified, for use with the bind() function.
177 The fields ai_family, ai_socktype, and ai_protocol shall be usable as
178 the arguments to the socket() function to create a socket suitable for
179 use with the returned address. The fields ai_addr and ai_addrlen are
180 usable as the arguments to the connect() or bind() functions with such
181 a socket, according to the AI_PASSIVE flag.
182 If nodename is not null, and if requested by the AI_CANONNAME flag, the
184 ai_canonname field of the first returned addrinfo structure shall point
185 to a null-terminated string containing the canonical name corresponding
186 to the input nodename; if the canonical name is not available, then
187 ai_canonname shall refer to the nodename argument or a string with the
188 same contents. The contents of the ai_flags field of the returned
189 structures are undefined.
190 All fields in socket address structures returned by getaddrinfo() that
192 are not filled in through an explicit argument (for example, sin6_flow‐
193 info) shall be set to zero.
194 Note: This makes it easier to compare socket address structures.
196
199 The getaddrinfo() function shall fail and return the corresponding
200 value if:
201 EAI_AGAIN
203 The name could not be resolved at this time. Future attempts may
204 succeed.
205 EAI_BADFLAGS
207 The flags parameter had an invalid value.
209 EAI_FAIL
211 A non-recoverable error occurred when attempting to resolve the
212 name.
213 EAI_FAMILY
215 The address family was not recognized.
216 EAI_MEMORY
218 There was a memory allocation failure when trying to allocate
219 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 of these
225 shall be supplied.
226 EAI_SERVICE
228 The service passed was not recognized for the specified socket
229 type.
230 EAI_SOCKTYPE
232 The intended socket type was not recognized.
234 EAI_SYSTEM
236 A system error occurred; the error code can be found in errno.
237 EAI_OVERFLOW
239 An argument buffer overflowed.
241 The following sections are informative.
244
246 None.
247
249 If the caller handles only TCP and not UDP, for example, then the
250 ai_protocol member of the hints structure should be set to IPPROTO_TCP
251 when getaddrinfo() is called.
252 If the caller handles only IPv4 and not IPv6, then the ai_family member
254 of the hints structure should be set to AF_INET when getaddrinfo() is
255 called.
256 The term ``canonical name'' is misleading; it is taken from the Domain
258 Name System (RFC 2181). It should be noted that the canonical name is a
259 result of alias processing, and not necessarily a unique attribute of a
260 host, address, or set of addresses. See RFC 2181 for more discussion of
261 this in the Domain Name System context.
262
264 None.
265
267 None.
268
270 connect() , gai_strerror() , gethostbyaddr() , getnameinfo() , get‐
271 servbyname() , socket() , the Base Definitions volume of
272 IEEE Std 1003.1-2001, <netdb.h>, <sys/socket.h>
273
275 Portions of this text are reprinted and reproduced in electronic form
276 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
277 -- Portable Operating System Interface (POSIX), The Open Group Base
278 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
279 Electrical and Electronics Engineers, Inc and The Open Group. In the
280 event of any discrepancy between this version and the original IEEE and
281 The Open Group Standard, the original IEEE and The Open Group Standard
282 is the referee document. The original Standard can be obtained online
283 at http://www.opengroup.org/unix/online.html .
284IEEE/The Open Group 2003 FREEADDRINFO(P)