]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com> |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
11 | .\" | |
12 | .\" Since the Linux kernel and libraries are constantly changing, this | |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
19 | .\" | |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" References: RFC 2553 | |
8d18d6ed MK |
24 | .\" |
25 | .\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED, | |
26 | .\" and AI_NUMERICSERV. | |
27 | .\" | |
fea681da MK |
28 | .TH getaddrinfo 3 2000-12-18 "Linux Man Page" "Linux Programmer's Manual" |
29 | .SH NAME | |
30 | getaddrinfo, freeaddrinfo, gai_strerror \- network address and service translation | |
31 | .SH SYNOPSIS | |
32 | .nf | |
33 | .B #include <sys/types.h> | |
34 | .B #include <sys/socket.h> | |
35 | .B #include <netdb.h> | |
36 | .sp | |
37 | .BI "int getaddrinfo(const char *" "node" ", const char *" "service" , | |
38 | .BI " const struct addrinfo *" "hints" , | |
39 | .BI " struct addrinfo **" "res" ); | |
40 | .sp | |
41 | .BI "void freeaddrinfo(struct addrinfo *" "res" ); | |
42 | .sp | |
43 | .BI "const char *gai_strerror(int " "errcode" ); | |
44 | .fi | |
45 | .SH DESCRIPTION | |
46 | The | |
47 | .BR getaddrinfo (3) | |
48 | function combines the functionality provided by the | |
49 | .BR getipnodebyname (3), | |
50 | .BR getipnodebyaddr (3), | |
51 | .BR getservbyname (3), | |
52 | and | |
53 | .BR getservbyport (3) | |
54 | functions into a single interface. | |
55 | The thread-safe | |
56 | .BR getaddrinfo (3) | |
57 | function creates one or more socket address structures that can be used by the | |
58 | .BR bind (2) | |
59 | and | |
60 | .BR connect (2) | |
61 | system calls to create a client or a server socket. | |
62 | .PP | |
63 | The | |
64 | .BR getaddrinfo (3) | |
65 | function is not limited to creating IPv4 socket address structures; | |
66 | IPv6 socket address structures can be created if IPv6 support is available. | |
67 | These socket address structures can be used directly by | |
68 | .BR bind (2) | |
69 | or | |
70 | .BR connect (2), | |
71 | to prepare a client or a server socket. | |
72 | .PP | |
73 | The | |
74 | .B addrinfo | |
75 | structure used by this function contains the following members: | |
76 | .sp | |
77 | .nf | |
78 | .B struct addrinfo { | |
79 | .BI " int " "ai_flags" ";" | |
80 | .BI " int " "ai_family" ";" | |
81 | .BI " int " "ai_socktype" ";" | |
82 | .BI " int " "ai_protocol" ";" | |
83 | .BI " size_t " "ai_addrlen" ";" | |
84 | .BI " struct sockaddr *" "ai_addr" ";" | |
85 | .BI " char *" "ai_canonname" ";" | |
86 | .BI " struct addrinfo *" "ai_next" ";" | |
87 | .B }; | |
88 | .fi | |
89 | .PP | |
90 | .BR getaddrinfo (3) | |
91 | sets | |
92 | .I res | |
8194de33 | 93 | to point to a dynamically-allocated linked list of |
fea681da MK |
94 | .B addrinfo |
95 | structures, linked by the | |
96 | .I ai_next | |
97 | member. | |
98 | There are several reasons why | |
8194de33 | 99 | the linked list may have more than one |
fea681da MK |
100 | .B addrinfo |
101 | structure, including: if the network host is | |
102 | multi-homed; or if the same service | |
103 | is available from multiple socket protocols (one | |
104 | .B SOCK_STREAM | |
105 | address and another | |
106 | .B SOCK_DGRAM | |
107 | address, for example). | |
108 | .PP | |
109 | The members | |
110 | .IR ai_family , | |
111 | .IR ai_socktype , | |
112 | and | |
113 | .I ai_protocol | |
114 | have the same meaning as the corresponding parameters in the | |
115 | .BR socket (2) | |
116 | system call. | |
117 | The | |
118 | .BR getaddrinfo (3) | |
119 | function returns socket addresses in either IPv4 or IPv6 | |
120 | address family, | |
121 | .RI "(" "ai_family" | |
122 | will be set to either | |
8d18d6ed | 123 | .B AF_INET |
fea681da | 124 | or |
8d18d6ed | 125 | .BR AF_INET6 ). |
fea681da MK |
126 | .PP |
127 | The | |
128 | .I hints | |
129 | parameter specifies | |
130 | the preferred socket type, or protocol. | |
131 | A NULL | |
132 | .I hints | |
133 | specifies that any network address or protocol is acceptable. | |
8d18d6ed | 134 | If this parameter is not NULL it points to an |
fea681da MK |
135 | .B addrinfo |
136 | structure | |
137 | whose | |
138 | .IR ai_family , | |
139 | .IR ai_socktype , | |
140 | and | |
141 | .I ai_protocol | |
142 | members specify the preferred socket type. | |
8d18d6ed | 143 | .B AF_UNSPEC |
fea681da MK |
144 | in |
145 | .I ai_family | |
146 | specifies any protocol family (either IPv4 or IPv6, for example). | |
147 | 0 in | |
148 | .I ai_socktype | |
149 | or | |
150 | .I ai_protocol | |
151 | specifies that any socket type or protocol is acceptable as well. | |
152 | The | |
153 | .I ai_flags | |
154 | member | |
155 | specifies additional options, defined below. | |
156 | Multiple flags are specified by logically OR-ing them together. | |
157 | All the other members in the | |
158 | .I hints | |
159 | parameter must contain either 0, or a null pointer. | |
160 | .PP | |
161 | The | |
162 | .I node | |
163 | or | |
164 | .I service | |
165 | parameter, but not both, may be NULL. | |
166 | .I node | |
167 | specifies either a numerical network address | |
168 | (dotted-decimal format for IPv4, hexadecimal format for IPv6) | |
169 | or a network hostname, whose network addresses are looked up and resolved. | |
8d18d6ed MK |
170 | If |
171 | .I hints.ai_flags | |
172 | contains the | |
fea681da MK |
173 | .B AI_NUMERICHOST |
174 | flag then the | |
175 | .I node | |
176 | parameter must be a numerical network address. | |
177 | The | |
178 | .B AI_NUMERICHOST | |
179 | flag suppresses any potentially lengthy network host address lookups. | |
180 | .PP | |
181 | The | |
182 | .BR getaddrinfo (3) | |
8194de33 | 183 | function creates a linked list of |
fea681da MK |
184 | .B addrinfo |
185 | structures, one for each network address subject to any restrictions | |
186 | imposed by the | |
187 | .I hints | |
188 | parameter. | |
8194de33 | 189 | The |
fea681da | 190 | .I ai_canonname |
8194de33 MK |
191 | field of the first of these |
192 | .B addrinfo | |
193 | structures is set to point to the official name of the host, if | |
8d18d6ed | 194 | .I hints.ai_flags |
fea681da MK |
195 | includes the |
196 | .B AI_CANONNAME | |
197 | flag. | |
8194de33 MK |
198 | .\" In glibc prior to 2.3.4, the ai_canonname of each addrinfo |
199 | .\" structure was set pointing to the canonical name; that was | |
200 | .\" more than SUSv3 specified, or other implementations provided. | |
201 | .\" MTK, Aug 05 | |
fea681da MK |
202 | .IR ai_family , |
203 | .IR ai_socktype , | |
204 | and | |
205 | .I ai_protocol | |
206 | specify the socket creation parameters. | |
207 | A pointer to the socket address is placed in the | |
208 | .I ai_addr | |
209 | member, and the length of the socket address, in bytes, | |
210 | is placed in the | |
211 | .I ai_addrlen | |
212 | member. | |
213 | .PP | |
214 | If | |
215 | .I node | |
216 | is NULL, | |
217 | the | |
218 | network address in each socket structure is initialized according to the | |
219 | .B AI_PASSIVE | |
8d18d6ed MK |
220 | flag, which is set in |
221 | .IR hints.ai_flags . | |
fea681da MK |
222 | The network address in each socket structure will be left unspecified |
223 | if | |
224 | .B AI_PASSIVE | |
225 | flag is set. | |
226 | This is used by server applications, which intend to accept | |
227 | client connections on any network address. | |
228 | The network address will be set to the loopback interface address | |
229 | if the | |
230 | .B AI_PASSIVE | |
231 | flag is not set. | |
232 | This is used by client applications, which intend to connect | |
233 | to a server running on the same network host. | |
234 | .PP | |
8d18d6ed MK |
235 | If |
236 | .I hints.ai_flags | |
237 | includes the | |
238 | .B AI_ADDRCONFIG | |
239 | flag, then IPv4 addresses are returned in the list pointed to by | |
240 | .I result | |
241 | only if the local system has at least has at least one | |
242 | IPv4 address configured, and IPv6 addresses are only returned | |
243 | if the local system has at least one IPv6 address configured. | |
244 | .PP | |
245 | If | |
246 | .I hint.ai_flags | |
247 | specifies the | |
248 | .B AI_V4MAPPED | |
249 | flag, and | |
250 | .I hints.ai_family | |
251 | was specified as | |
252 | .BR AF_INET6 , | |
253 | and no matching IPv6 addresses could be found, | |
254 | then return IPv4-mapped IPv6 addresses in the list pointed to by | |
255 | .IR result . | |
256 | If both | |
257 | .B AI_V4MAPPED | |
258 | and | |
259 | .B AI_ALL | |
260 | are specified in | |
261 | .IR hints.ai_family , | |
262 | then return both IPv6 and IPv4-mapped IPv6 addresses | |
263 | in the list pointed to by | |
264 | .IR result . | |
265 | .B AI_ALL | |
266 | is ignored if | |
267 | .B AI_V4MAPPED | |
268 | is not also specified. | |
269 | .PP | |
fea681da MK |
270 | .I service |
271 | sets the port number in the network address of each socket structure. | |
272 | If | |
273 | .I service | |
274 | is NULL the port number will be left uninitialized. | |
8d18d6ed MK |
275 | If |
276 | .B AI_NUMERICSERV | |
277 | is specified in | |
278 | .IR hints.ai_flags | |
279 | and | |
280 | .I service | |
281 | is not NULL, then | |
282 | .I service | |
283 | must point to a string containing a numeric port number. | |
284 | This flag is used to inhibit the invocation of a name resolution service | |
285 | in cases where it is known not to be required. | |
fea681da MK |
286 | .PP |
287 | The | |
288 | .BR freeaddrinfo (3) | |
289 | function frees the memory that was allocated | |
8194de33 | 290 | for the dynamically allocated linked list |
fea681da MK |
291 | .IR res . |
292 | .SH "RETURN VALUE" | |
293 | .BR getaddrinfo (3) | |
294 | returns 0 if it succeeds, or one of the following non-zero error codes: | |
295 | .TP | |
296 | .B EAI_FAMILY | |
297 | The requested address family is not supported at all. | |
298 | .TP | |
299 | .B EAI_SOCKTYPE | |
300 | The requested socket type is not supported at all. | |
301 | .TP | |
302 | .B EAI_BADFLAGS | |
303 | .I ai_flags | |
304 | contains invalid flags. | |
305 | .TP | |
306 | .B EAI_NONAME | |
307 | The | |
308 | .I node | |
309 | or | |
310 | .I service | |
8d18d6ed | 311 | is not known; or both |
fea681da MK |
312 | .I node |
313 | and | |
314 | .I service | |
8d18d6ed MK |
315 | are NULL; or |
316 | .B AI_NUMERICSERV | |
317 | was specified in | |
318 | .I hints.ai_flags | |
319 | and | |
320 | .I service | |
321 | was not a numeric port-number string. | |
fea681da MK |
322 | .TP |
323 | .B EAI_SERVICE | |
324 | The requested service is not available for the requested socket type. | |
325 | It may be available through another socket type. | |
326 | .TP | |
327 | .B EAI_ADDRFAMILY | |
328 | The specified network host does not have any network addresses in the | |
329 | requested address family. | |
330 | .TP | |
331 | .B EAI_NODATA | |
332 | The specified network host exists, but does not have any | |
333 | network addresses defined. | |
334 | .TP | |
335 | .B EAI_MEMORY | |
336 | Out of memory. | |
337 | .TP | |
338 | .B EAI_FAIL | |
339 | The name server returned a permanent failure indication. | |
340 | .TP | |
341 | .B EAI_AGAIN | |
342 | The name server returned a temporary failure indication. | |
343 | Try again later. | |
344 | .TP | |
345 | .B EAI_SYSTEM | |
346 | Other system error, check | |
347 | .I errno | |
348 | for details. | |
349 | .PP | |
350 | The | |
351 | .BR gai_strerror (3) | |
352 | function translates these error codes to a human readable string, | |
353 | suitable for error reporting. | |
354 | .SH "CONFORMING TO" | |
355 | POSIX 1003.1-2003. | |
356 | The | |
357 | .B getaddrinfo() | |
331da7c3 | 358 | function is documented in RFC\ 2553. |
8d18d6ed MK |
359 | .SH "NOTES" |
360 | .BR AI_ADDRCONFIG , | |
361 | .BR AI_ALL, | |
362 | and | |
363 | .BR AI_V4MAPPED | |
364 | are available since glibc 2.3.3. | |
365 | .BR AI_NUMERICSERV | |
366 | is available since glibc 2.3.4. | |
fea681da MK |
367 | .SH "SEE ALSO" |
368 | .BR getipnodebyaddr (3), | |
369 | .BR getipnodebyname (3) |