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
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.
43 The nodename and servname arguments are either null pointers or point‐
45 ers to null-terminated strings. One or both of these two arguments
46 shall be supplied by the application as a non-null pointer.
47 The format of a valid name depends on the address family or families.
49 If a specific family is not given and the name could be interpreted as
50 valid within multiple supported families, the implementation shall
51 attempt to resolve the name in all supported families and, in absence
52 of errors, one or more results shall be returned.
53 If the nodename argument is not null, it can be a descriptive name or
55 can be an address string. If the specified address family is AF_INET,
56 AF_INET6, or AF_UNSPEC, valid descriptive names include host names. If
57 the specified address family is AF_INET or AF_UNSPEC, address strings
58 using Internet standard dot notation as specified in inet_addr() are
59 valid.
60 If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
62 text forms described in inet_ntop() are valid.
63 If nodename is not null, the requested service location is named by
65 nodename; otherwise, the requested service location is local to the
66 caller.
67 If servname is null, the call shall return network-level addresses for
69 the specified nodename. If servname is not null, it is a null-termi‐
70 nated character string identifying the requested service. This can be
71 either a descriptive name or a numeric representation suitable for use
72 with the address family or families. If the specified address family is
73 AF_INET, AF_INET6, or AF_UNSPEC, the service can be specified as a
74 string specifying a decimal port number.
75 If the hints argument is not null, it refers to a structure containing
77 input values that may direct the operation by providing options and by
78 limiting the returned information to a specific socket type, address
79 family, and/or protocol. In this hints structure every member other
80 than ai_flags, ai_family, ai_socktype, and ai_protocol shall be set to
81 zero or a null pointer. A value of AF_UNSPEC for ai_family means that
82 the caller shall accept any address family. A value of zero for
83 ai_socktype means that the caller shall accept any socket type. A value
84 of zero for ai_protocol means that the caller shall accept any proto‐
85 col. If hints is a null pointer, the behavior shall be as if it
86 referred to a structure containing the value zero for the ai_flags,
87 ai_socktype, and ai_protocol fields, and AF_UNSPEC for the ai_family
88 field.
89 The ai_flags field to which the hints parameter points shall be set to
91 zero or be the bitwise-inclusive OR of one or more of the values
92 AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED,
93 AI_ALL, and AI_ADDRCONFIG.
94 If the AI_PASSIVE flag is specified, the returned address information
96 shall be suitable for use in binding a socket for accepting incoming
97 connections for the specified service. In this case, if the nodename
98 argument is null, then the IP address portion of the socket address
99 structure shall be set to INADDR_ANY for an IPv4 address or
100 IN6ADDR_ANY_INIT for an IPv6 address. If the AI_PASSIVE flag is not
101 specified, the returned address information shall be suitable for a
102 call to connect() (for a connection-mode protocol) or for a call to
103 connect(), sendto(), or sendmsg() (for a connectionless protocol). In
104 this case, if the nodename argument is null, then the IP address por‐
105 tion of the socket address structure shall be set to the loopback
106 address. The AI_PASSIVE flag shall be ignored if the nodename argument
107 is not null.
108 If the AI_CANONNAME flag is specified and the nodename argument is not
110 null, the function shall attempt to determine the canonical name corre‐
111 sponding to nodename (for example, if nodename is an alias or shorthand
112 notation for a complete name).
113 Note: Since different implementations use different conceptual models,
115 the terms ``canonical name'' and ``alias'' cannot be precisely
116 defined for the general case. However, Domain Name System imple‐
117 mentations are expected to interpret them as they are used in
118 RFC 1034.
119 A numeric host address string is not a ``name'', and thus does not have
121 a ``canonical name'' form; no address to host name translation is per‐
122 formed. See below for handling of the case where a canonical name can‐
123 not be obtained.
124 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 If the AI_V4MAPPED flag is specified along with an ai_family of
137 AF_INET6, then getaddrinfo() shall return IPv4-mapped IPv6 addresses on
138 finding no matching IPv6 addresses ( ai_addrlen shall be 16). The
139 AI_V4MAPPED flag shall be ignored unless ai_family equals AF_INET6. If
140 the AI_ALL flag is used with the AI_V4MAPPED flag, then getaddrinfo()
141 shall return all matching IPv6 and IPv4 addresses. The AI_ALL flag
142 without the AI_V4MAPPED flag is ignored.
143 If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be
145 returned only if an IPv4 address is configured on the local system,
146 and IPv6 addresses shall be returned only if an IPv6 address is config‐
147 ured on the local system.
148 The ai_socktype field to which argument hints points specifies the
150 socket type for the service, as defined in socket(). If a specific
151 socket type is not given (for example, a value of zero) and the service
152 name could be interpreted as valid with multiple supported socket
153 types, the implementation shall attempt to resolve the service name for
154 all supported socket types and, in the absence of errors, all possible
155 results shall be returned. A non-zero socket type value shall limit the
156 returned information to values with the specified socket type.
157 If the ai_family field to which hints points has the value AF_UNSPEC,
159 addresses shall be returned for use with any address family that can be
160 used with the specified nodename and/or servname. Otherwise, addresses
161 shall be returned for use only with the specified address family. If
162 ai_family is not AF_UNSPEC and ai_protocol is not zero, then addresses
163 are returned for use only with the specified address family and proto‐
164 col; the value of ai_protocol shall be interpreted as in a call to the
165 socket() function with the corresponding values of ai_family and
166 ai_protocol.
167
169 A zero return value for getaddrinfo() indicates successful completion;
170 a non-zero return value indicates failure. The possible values for the
171 failures are listed in the ERRORS section.
172 Upon successful return of getaddrinfo(), the location to which res
174 points shall refer to a linked list of addrinfo structures, each of
175 which shall specify a socket address and information for use in creat‐
176 ing a socket with which to use that socket address. The list shall
177 include at least one addrinfo structure. The ai_next field of each
178 structure contains a pointer to the next structure on the list, or a
179 null pointer if it is the last structure on the list. Each structure on
180 the list shall include values for use with a call to the socket() func‐
181 tion, and a socket address for use with the connect() function or, if
182 the AI_PASSIVE flag was specified, for use with the bind() function.
183 The fields ai_family, ai_socktype, and ai_protocol shall be usable as
184 the arguments to the socket() function to create a socket suitable for
185 use with the returned address. The fields ai_addr and ai_addrlen are
186 usable as the arguments to the connect() or bind() functions with such
187 a socket, according to the AI_PASSIVE flag.
188 If nodename is not null, and if requested by the AI_CANONNAME flag, the
190 ai_canonname field of the first returned addrinfo structure shall point
191 to a null-terminated string containing the canonical name corresponding
192 to the input nodename; if the canonical name is not available, then
193 ai_canonname shall refer to the nodename argument or a string with the
194 same contents. The contents of the ai_flags field of the returned
195 structures are undefined.
196 All fields in socket address structures returned by getaddrinfo() that
198 are not filled in through an explicit argument (for example, sin6_flow‐
199 info) shall be set to zero.
200 Note: This makes it easier to compare socket address structures.
202
205 The getaddrinfo() function shall fail and return the corresponding
206 value if:
207 EAI_AGAIN
209 The name could not be resolved at this time. Future attempts may
210 succeed.
211 EAI_BADFLAGS
213 The flags parameter had an invalid value.
215 EAI_FAIL
217 A non-recoverable error occurred when attempting to resolve the
218 name.
219 EAI_FAMILY
221 The address family was not recognized.
222 EAI_MEMORY
224 There was a memory allocation failure when trying to allocate
225 storage for the return value.
226 EAI_NONAME
228 The name does not resolve for the supplied parameters.
229 Neither nodename nor servname were supplied. At least one of these
231 shall be supplied.
232 EAI_SERVICE
234 The service passed was not recognized for the specified socket
235 type.
236 EAI_SOCKTYPE
238 The intended socket type was not recognized.
240 EAI_SYSTEM
242 A system error occurred; the error code can be found in errno.
243 EAI_OVERFLOW
245 An argument buffer overflowed.
247 The following sections are informative.
250
252 None.
253
255 If the caller handles only TCP and not UDP, for example, then the
256 ai_protocol member of the hints structure should be set to IPPROTO_TCP
257 when getaddrinfo() is called.
258 If the caller handles only IPv4 and not IPv6, then the ai_family member
260 of the hints structure should be set to AF_INET when getaddrinfo() is
261 called.
262 The term ``canonical name'' is misleading; it is taken from the Domain
264 Name System (RFC 2181). It should be noted that the canonical name is a
265 result of alias processing, and not necessarily a unique attribute of a
266 host, address, or set of addresses. See RFC 2181 for more discussion of
267 this in the Domain Name System context.
268
270 None.
271
273 None.
274
276 connect(), gai_strerror(), gethostbyaddr(), getnameinfo(), getservby‐
277 name(), socket(), the Base Definitions volume of IEEE Std 1003.1-2001,
278 <netdb.h>, <sys/socket.h>
279
281 Portions of this text are reprinted and reproduced in electronic form
282 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
283 -- Portable Operating System Interface (POSIX), The Open Group Base
284 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
285 Electrical and Electronics Engineers, Inc and The Open Group. In the
286 event of any discrepancy between this version and the original IEEE and
287 The Open Group Standard, the original IEEE and The Open Group Standard
288 is the referee document. The original Standard can be obtained online
289 at http://www.opengroup.org/unix/online.html .
290IEEE/The Open Group 2003 FREEADDRINFO(3P)