1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
1 |
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved |
2
by Francesco Paolo Lovergine
* Alligned to linux main manpages edition. |
2 |
.TH "FREEADDRINFO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" |
1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
3 |
.\" freeaddrinfo |
4 |
.SH NAME |
|
5 |
freeaddrinfo, getaddrinfo \- get address information
|
|
6 |
.SH SYNOPSIS |
|
7 |
.LP
|
|
8 |
\fB#include <sys/socket.h>
|
|
9 |
.br
|
|
10 |
#include <netdb.h> |
|
11 |
.br
|
|
12 |
.sp
|
|
13 |
void freeaddrinfo(struct addrinfo *\fP\fIai\fP\fB); |
|
14 |
.br
|
|
15 |
int getaddrinfo(const char *restrict\fP \fInodename\fP\fB, |
|
16 |
.br
|
|
17 |
\ \ \ \ \ \ const char *restrict\fP \fIservname\fP\fB, |
|
18 |
.br
|
|
19 |
\ \ \ \ \ \ const struct addrinfo *restrict\fP \fIhints\fP\fB, |
|
20 |
.br
|
|
21 |
\ \ \ \ \ \ struct addrinfo **restrict\fP \fIres\fP\fB); |
|
22 |
.br
|
|
23 |
\fP
|
|
24 |
.SH DESCRIPTION |
|
25 |
.LP
|
|
26 |
The \fIfreeaddrinfo\fP() function shall free one or more \fBaddrinfo\fP |
|
27 |
structures returned by \fIgetaddrinfo\fP(), along |
|
28 |
with any additional storage associated with those structures. If the |
|
29 |
\fIai_next\fP field of the structure is not null, the entire |
|
30 |
list of structures shall be freed. The \fIfreeaddrinfo\fP() function |
|
31 |
shall support the freeing of arbitrary sublists of an |
|
32 |
\fBaddrinfo\fP list originally returned by \fIgetaddrinfo\fP(). |
|
33 |
.LP
|
|
34 |
The \fIgetaddrinfo\fP() function shall translate the name of a service |
|
35 |
location (for example, a host name) and/or a service |
|
36 |
name and shall return a set of socket addresses and associated information |
|
37 |
to be used in creating a socket with which to address |
|
38 |
the specified service. |
|
39 |
.TP 7 |
|
40 |
\fBNote:\fP |
|
41 |
In many cases it is implemented by the Domain Name System, as documented |
|
42 |
in RFC\ 1034, RFC\ 1035, and |
|
43 |
RFC\ 1886.
|
|
44 |
.sp
|
|
45 |
.LP
|
|
46 |
The \fIfreeaddrinfo\fP() and \fIgetaddrinfo\fP() functions shall be |
|
47 |
thread-safe. |
|
48 |
.LP
|
|
49 |
The \fInodename\fP and \fIservname\fP arguments are either null pointers |
|
50 |
or pointers to null-terminated strings. One or both |
|
51 |
of these two arguments shall be supplied by the application as a non-null |
|
52 |
pointer. |
|
53 |
.LP
|
|
54 |
The format of a valid name depends on the address family or families. |
|
55 |
If a specific family is not given and the name could be |
|
56 |
interpreted as valid within multiple supported families, the implementation |
|
57 |
shall attempt to resolve the name in all supported |
|
58 |
families and, in absence of errors, one or more results shall be returned. |
|
59 |
.LP
|
|
60 |
If the \fInodename\fP argument is not null, it can be a descriptive |
|
61 |
name or can be an address string. If the specified address |
|
62 |
family is AF_INET, \ AF_INET6, or AF_UNSPEC, valid
|
|
63 |
descriptive names include host names. If the specified address family |
|
64 |
is AF_INET or AF_UNSPEC, address strings using Internet |
|
65 |
standard dot notation as specified in \fIinet_addr\fP() are valid. |
|
66 |
.LP
|
|
67 |
If the specified address family is AF_INET6 or AF_UNSPEC, standard |
|
68 |
IPv6 text forms described in \fIinet_ntop\fP() are valid. |
|
69 |
.LP
|
|
70 |
If \fInodename\fP is not null, the requested service location is named |
|
71 |
by \fInodename\fP; otherwise, the requested service |
|
72 |
location is local to the caller. |
|
73 |
.LP
|
|
74 |
If \fIservname\fP is null, the call shall return network-level addresses |
|
75 |
for the specified \fInodename.\fP If \fIservname\fP |
|
76 |
is not null, it is a null-terminated character string identifying |
|
77 |
the requested service. This can be either a descriptive name or a |
|
78 |
numeric representation suitable for use with the address family or |
|
79 |
families. If the specified address family is AF_INET, |
|
80 |
\ AF_INET6, or AF_UNSPEC, the service can be specified as a
|
|
81 |
string specifying a decimal port number. |
|
82 |
.LP
|
|
83 |
If the \fIhints\fP argument is not null, it refers to a structure |
|
84 |
containing input values that may direct the operation by |
|
85 |
providing options and by limiting the returned information to a specific |
|
86 |
socket type, address family, and/or protocol. In this |
|
87 |
\fIhints\fP structure every member other than \fIai_flags\fP, \fIai_family\fP, |
|
88 |
\fIai_socktype\fP, and \fIai_protocol\fP shall |
|
89 |
be set to zero or a null pointer. A value of AF_UNSPEC for \fIai_family\fP |
|
90 |
means that the caller shall accept any address family. |
|
91 |
A value of zero for \fIai_socktype\fP means that the caller shall |
|
92 |
accept any socket type. A value of zero for \fIai_protocol\fP |
|
93 |
means that the caller shall accept any protocol. If \fIhints\fP is |
|
94 |
a null pointer, the behavior shall be as if it referred to a |
|
95 |
structure containing the value zero for the \fIai_flags\fP, \fIai_socktype\fP, |
|
96 |
and \fIai_protocol\fP fields, and AF_UNSPEC for |
|
97 |
the \fIai_family\fP field. |
|
98 |
.LP
|
|
99 |
The \fIai_flags\fP field to which the \fIhints\fP parameter points |
|
100 |
shall be set to zero or be the bitwise-inclusive OR of one |
|
101 |
or more of the values AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, |
|
102 |
AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG. |
|
103 |
.LP
|
|
104 |
If the AI_PASSIVE flag is specified, the returned address information |
|
105 |
shall be suitable for use in binding a socket for |
|
106 |
accepting incoming connections for the specified service. In this |
|
107 |
case, if the \fInodename\fP argument is null, then the IP |
|
108 |
address portion of the socket address structure shall be set to INADDR_ANY |
|
109 |
for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 |
|
110 |
address. If the AI_PASSIVE flag is not specified, the returned address |
|
111 |
information shall be suitable for a call to \fIconnect\fP() (for a |
|
112 |
connection-mode protocol) or for a call to \fIconnect\fP(), \fIsendto\fP(), |
|
113 |
or \fIsendmsg\fP() (for a connectionless protocol). In this case, |
|
114 |
if the \fInodename\fP argument is |
|
115 |
null, then the IP address portion of the socket address structure |
|
116 |
shall be set to the loopback address. The AI_PASSIVE flag shall |
|
117 |
be ignored if the \fInodename\fP argument is not null. |
|
118 |
.LP
|
|
119 |
If the AI_CANONNAME flag is specified and the \fInodename\fP argument |
|
120 |
is not null, the function shall attempt to determine the |
|
121 |
canonical name corresponding to \fInodename\fP (for example, if \fInodename\fP |
|
122 |
is an alias or shorthand notation for a complete |
|
123 |
name). |
|
124 |
.TP 7 |
|
125 |
\fBNote:\fP |
|
126 |
Since different implementations use different conceptual models, the |
|
127 |
terms ``canonical name'' and ``alias'' cannot be precisely |
|
128 |
defined for the general case. However, Domain Name System implementations |
|
129 |
are expected to interpret them as they are used in |
|
130 |
RFC\ 1034.
|
|
131 |
.LP
|
|
132 |
A numeric host address string is not a ``name'', and thus does not |
|
133 |
have a ``canonical name'' form; no address to host name |
|
134 |
translation is performed. See below for handling of the case where |
|
135 |
a canonical name cannot be obtained. |
|
136 |
.sp
|
|
137 |
.LP
|
|
138 |
If the AI_NUMERICHOST flag is specified, then a non-null \fInodename\fP |
|
139 |
string supplied shall be a numeric host address string. |
|
140 |
Otherwise, an [EAI_NONAME] error is returned. This flag shall prevent |
|
141 |
any type of name resolution service (for example, the DNS) |
|
142 |
from being invoked. |
|
143 |
.LP
|
|
144 |
If the AI_NUMERICSERV flag is specified, then a non-null \fIservname\fP |
|
145 |
string supplied shall be a numeric port string. |
|
146 |
Otherwise, an [EAI_NONAME] error shall be returned. This flag shall |
|
147 |
prevent any type of name resolution service (for example, NIS+) |
|
148 |
from being invoked. |
|
149 |
.LP
|
|
150 |
If the AI_V4MAPPED flag is specified along with an \fIai_family\fP |
|
151 |
of AF_INET6, then \fIgetaddrinfo\fP() shall return IPv4-mapped |
|
152 |
IPv6 addresses on finding no matching IPv6 addresses ( \fIai_addrlen\fP |
|
153 |
shall be 16). The AI_V4MAPPED flag shall be ignored unless |
|
154 |
\fIai_family\fP equals AF_INET6. If the AI_ALL flag is used with the |
|
155 |
AI_V4MAPPED flag, then \fIgetaddrinfo\fP() shall return all |
|
156 |
matching IPv6 and IPv4 addresses. The AI_ALL flag without the AI_V4MAPPED |
|
157 |
flag is ignored. |
|
158 |
.LP
|
|
159 |
If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be returned |
|
160 |
only if an IPv4 address is configured on the local |
|
161 |
system, \ and IPv6 addresses shall be returned only if an IPv6 address
|
|
162 |
is configured on the local system. |
|
163 |
.LP
|
|
164 |
The \fIai_socktype\fP field to which argument \fIhints\fP points specifies |
|
165 |
the socket type for the service, as defined in \fIsocket\fP() . If |
|
166 |
a specific socket type is not given (for example, a value of zero) |
|
167 |
and the service name |
|
168 |
could be interpreted as valid with multiple supported socket types, |
|
169 |
the implementation shall attempt to resolve the service name |
|
170 |
for all supported socket types and, in the absence of errors, all |
|
171 |
possible results shall be returned. A non-zero socket type value |
|
172 |
shall limit the returned information to values with the specified |
|
173 |
socket type. |
|
174 |
.LP
|
|
175 |
If the \fIai_family\fP field to which \fIhints\fP points has the value |
|
176 |
AF_UNSPEC, addresses shall be returned for use with any |
|
177 |
address family that can be used with the specified \fInodename\fP |
|
178 |
and/or \fIservname\fP. Otherwise, addresses shall be returned |
|
179 |
for use only with the specified address family. If \fIai_family\fP |
|
180 |
is not AF_UNSPEC and \fIai_protocol\fP is not zero, then |
|
181 |
addresses are returned for use only with the specified address family |
|
182 |
and protocol; the value of \fIai_protocol\fP shall be |
|
183 |
interpreted as in a call to the \fIsocket\fP() function with the corresponding |
|
184 |
values of |
|
185 |
\fIai_family\fP and \fIai_protocol\fP. |
|
186 |
.SH RETURN VALUE |
|
187 |
.LP
|
|
188 |
A zero return value for \fIgetaddrinfo\fP() indicates successful completion; |
|
189 |
a non-zero return value indicates failure. The |
|
190 |
possible values for the failures are listed in the ERRORS section. |
|
191 |
.LP
|
|
192 |
Upon successful return of \fIgetaddrinfo\fP(), the location to which |
|
193 |
\fIres\fP points shall refer to a linked list of |
|
194 |
\fBaddrinfo\fP structures, each of which shall specify a socket address |
|
195 |
and information for use in creating a socket with which to |
|
196 |
use that socket address. The list shall include at least one \fBaddrinfo\fP |
|
197 |
structure. The \fIai_next\fP field of each structure |
|
198 |
contains a pointer to the next structure on the list, or a null pointer |
|
199 |
if it is the last structure on the list. Each structure on |
|
200 |
the list shall include values for use with a call to the \fIsocket\fP() |
|
201 |
function, and a |
|
202 |
socket address for use with the \fIconnect\fP() function or, if the |
|
203 |
AI_PASSIVE flag was |
|
204 |
specified, for use with the \fIbind\fP() function. The fields \fIai_family\fP, |
|
205 |
\fIai_socktype\fP, and \fIai_protocol\fP shall be usable as the arguments |
|
206 |
to the \fIsocket\fP() function to create a socket suitable for use |
|
207 |
with the returned address. The fields |
|
208 |
\fIai_addr\fP and \fIai_addrlen\fP are usable as the arguments to |
|
209 |
the \fIconnect\fP() or |
|
210 |
\fIbind\fP() functions with such a socket, according to the AI_PASSIVE |
|
211 |
flag. |
|
212 |
.LP
|
|
213 |
If \fInodename\fP is not null, and if requested by the AI_CANONNAME |
|
214 |
flag, the \fIai_canonname\fP field of the first returned |
|
215 |
\fBaddrinfo\fP structure shall point to a null-terminated string containing |
|
216 |
the canonical name corresponding to the input |
|
217 |
\fInodename\fP; if the canonical name is not available, then \fIai_canonname\fP |
|
218 |
shall refer to the \fInodename\fP argument or a |
|
219 |
string with the same contents. The contents of the \fIai_flags\fP |
|
220 |
field of the returned structures are undefined. |
|
221 |
.LP
|
|
222 |
All fields in socket address structures returned by \fIgetaddrinfo\fP() |
|
223 |
that are not filled in through an explicit argument |
|
224 |
(for example, \fIsin6_flowinfo\fP) shall be set to zero. |
|
225 |
.TP 7 |
|
226 |
\fBNote:\fP |
|
227 |
This makes it easier to compare socket address structures. |
|
228 |
.sp
|
|
229 |
.SH ERRORS |
|
230 |
.LP
|
|
231 |
The \fIgetaddrinfo\fP() function shall fail and return the corresponding |
|
232 |
value if: |
|
233 |
.TP 7 |
|
234 |
.B EAI_AGAIN |
|
235 |
The name could not be resolved at this time. Future attempts may succeed. |
|
236 |
.TP 7 |
|
237 |
.B EAI_BADFLAGS |
|
238 |
.sp
|
|
239 |
The \fIflags\fP parameter had an invalid value. |
|
240 |
.TP 7 |
|
241 |
.B EAI_FAIL |
|
242 |
A non-recoverable error occurred when attempting to resolve the name. |
|
243 |
.TP 7 |
|
244 |
.B EAI_FAMILY |
|
245 |
The address family was not recognized. |
|
246 |
.TP 7 |
|
247 |
.B EAI_MEMORY |
|
248 |
There was a memory allocation failure when trying to allocate storage |
|
249 |
for the return value. |
|
250 |
.TP 7 |
|
251 |
.B EAI_NONAME |
|
252 |
The name does not resolve for the supplied parameters. |
|
253 |
.LP
|
|
254 |
Neither \fInodename\fP nor \fIservname\fP were supplied. At least |
|
255 |
one of these shall be supplied. |
|
256 |
.TP 7 |
|
257 |
.B EAI_SERVICE |
|
258 |
The service passed was not recognized for the specified socket type. |
|
259 |
.TP 7 |
|
260 |
.B EAI_SOCKTYPE |
|
261 |
.sp
|
|
262 |
The intended socket type was not recognized. |
|
263 |
.TP 7 |
|
264 |
.B EAI_SYSTEM |
|
265 |
A system error occurred; the error code can be found in \fIerrno\fP. |
|
266 |
.TP 7 |
|
267 |
.B EAI_OVERFLOW |
|
268 |
.sp
|
|
269 |
An argument buffer overflowed. |
|
270 |
.sp
|
|
271 |
.LP
|
|
272 |
\fIThe following sections are informative.\fP |
|
273 |
.SH EXAMPLES |
|
274 |
.LP
|
|
275 |
None. |
|
276 |
.SH APPLICATION USAGE |
|
277 |
.LP
|
|
278 |
If the caller handles only TCP and not UDP, for example, then the |
|
279 |
\fIai_protocol\fP member of the \fIhints\fP structure should |
|
280 |
be set to IPPROTO_TCP when \fIgetaddrinfo\fP() is called. |
|
281 |
.LP
|
|
282 |
If the caller handles only IPv4 and not IPv6, then the \fIai_family\fP |
|
283 |
member of the \fIhints\fP structure should be set to |
|
284 |
AF_INET when \fIgetaddrinfo\fP() is called. |
|
285 |
.LP
|
|
286 |
The term ``canonical name'' is misleading; it is taken from the Domain |
|
287 |
Name System (RFC\ 2181). It should be noted that the
|
|
288 |
canonical name is a result of alias processing, and not necessarily |
|
289 |
a unique attribute of a host, address, or set of addresses. See |
|
290 |
RFC\ 2181 for more discussion of this in the Domain Name System context.
|
|
291 |
.SH RATIONALE |
|
292 |
.LP
|
|
293 |
None. |
|
294 |
.SH FUTURE DIRECTIONS |
|
295 |
.LP
|
|
296 |
None. |
|
297 |
.SH SEE ALSO |
|
298 |
.LP
|
|
299 |
\fIconnect\fP() , \fIgai_strerror\fP() , \fIgethostbyaddr\fP() , \fIgetnameinfo\fP() |
|
300 |
, \fIgetservbyname\fP() , \fIsocket\fP() , the Base Definitions volume |
|
301 |
of |
|
302 |
IEEE\ Std\ 1003.1-2001, \fI<netdb.h>\fP, \fI<sys/socket.h>\fP |
|
303 |
.SH COPYRIGHT |
|
304 |
Portions of this text are reprinted and reproduced in electronic form |
|
305 |
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology |
|
306 |
-- Portable Operating System Interface (POSIX), The Open Group Base |
|
307 |
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of |
|
308 |
Electrical and Electronics Engineers, Inc and The Open Group. In the |
|
309 |
event of any discrepancy between this version and the original IEEE and |
|
310 |
The Open Group Standard, the original IEEE and The Open Group Standard |
|
311 |
is the referee document. The original Standard can be obtained online at |
|
312 |
http://www.opengroup.org/unix/online.html . |