]>
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 | |
24 | .TH getaddrinfo 3 2000-12-18 "Linux Man Page" "Linux Programmer's Manual" | |
25 | .SH NAME | |
26 | getaddrinfo, freeaddrinfo, gai_strerror \- network address and service translation | |
27 | .SH SYNOPSIS | |
28 | .nf | |
29 | .B #include <sys/types.h> | |
30 | .B #include <sys/socket.h> | |
31 | .B #include <netdb.h> | |
32 | .sp | |
33 | .BI "int getaddrinfo(const char *" "node" ", const char *" "service" , | |
34 | .BI " const struct addrinfo *" "hints" , | |
35 | .BI " struct addrinfo **" "res" ); | |
36 | .sp | |
37 | .BI "void freeaddrinfo(struct addrinfo *" "res" ); | |
38 | .sp | |
39 | .BI "const char *gai_strerror(int " "errcode" ); | |
40 | .fi | |
41 | .SH DESCRIPTION | |
42 | The | |
43 | .BR getaddrinfo (3) | |
44 | function combines the functionality provided by the | |
45 | .BR getipnodebyname (3), | |
46 | .BR getipnodebyaddr (3), | |
47 | .BR getservbyname (3), | |
48 | and | |
49 | .BR getservbyport (3) | |
50 | functions into a single interface. | |
51 | The thread-safe | |
52 | .BR getaddrinfo (3) | |
53 | function creates one or more socket address structures that can be used by the | |
54 | .BR bind (2) | |
55 | and | |
56 | .BR connect (2) | |
57 | system calls to create a client or a server socket. | |
58 | .PP | |
59 | The | |
60 | .BR getaddrinfo (3) | |
61 | function is not limited to creating IPv4 socket address structures; | |
62 | IPv6 socket address structures can be created if IPv6 support is available. | |
63 | These socket address structures can be used directly by | |
64 | .BR bind (2) | |
65 | or | |
66 | .BR connect (2), | |
67 | to prepare a client or a server socket. | |
68 | .PP | |
69 | The | |
70 | .B addrinfo | |
71 | structure used by this function contains the following members: | |
72 | .sp | |
73 | .nf | |
74 | .B struct addrinfo { | |
75 | .BI " int " "ai_flags" ";" | |
76 | .BI " int " "ai_family" ";" | |
77 | .BI " int " "ai_socktype" ";" | |
78 | .BI " int " "ai_protocol" ";" | |
79 | .BI " size_t " "ai_addrlen" ";" | |
80 | .BI " struct sockaddr *" "ai_addr" ";" | |
81 | .BI " char *" "ai_canonname" ";" | |
82 | .BI " struct addrinfo *" "ai_next" ";" | |
83 | .B }; | |
84 | .fi | |
85 | .PP | |
86 | .BR getaddrinfo (3) | |
87 | sets | |
88 | .I res | |
89 | to point to a dynamically-allocated link list of | |
90 | .B addrinfo | |
91 | structures, linked by the | |
92 | .I ai_next | |
93 | member. | |
94 | There are several reasons why | |
95 | the link list may have more than one | |
96 | .B addrinfo | |
97 | structure, including: if the network host is | |
98 | multi-homed; or if the same service | |
99 | is available from multiple socket protocols (one | |
100 | .B SOCK_STREAM | |
101 | address and another | |
102 | .B SOCK_DGRAM | |
103 | address, for example). | |
104 | .PP | |
105 | The members | |
106 | .IR ai_family , | |
107 | .IR ai_socktype , | |
108 | and | |
109 | .I ai_protocol | |
110 | have the same meaning as the corresponding parameters in the | |
111 | .BR socket (2) | |
112 | system call. | |
113 | The | |
114 | .BR getaddrinfo (3) | |
115 | function returns socket addresses in either IPv4 or IPv6 | |
116 | address family, | |
117 | .RI "(" "ai_family" | |
118 | will be set to either | |
119 | .B PF_INET | |
120 | or | |
121 | .BR PF_INET6 ). | |
122 | .PP | |
123 | The | |
124 | .I hints | |
125 | parameter specifies | |
126 | the preferred socket type, or protocol. | |
127 | A NULL | |
128 | .I hints | |
129 | specifies that any network address or protocol is acceptable. | |
130 | If this parameter is not | |
131 | .B NULL | |
132 | it points to an | |
133 | .B addrinfo | |
134 | structure | |
135 | whose | |
136 | .IR ai_family , | |
137 | .IR ai_socktype , | |
138 | and | |
139 | .I ai_protocol | |
140 | members specify the preferred socket type. | |
141 | .B PF_UNSPEC | |
142 | in | |
143 | .I ai_family | |
144 | specifies any protocol family (either IPv4 or IPv6, for example). | |
145 | 0 in | |
146 | .I ai_socktype | |
147 | or | |
148 | .I ai_protocol | |
149 | specifies that any socket type or protocol is acceptable as well. | |
150 | The | |
151 | .I ai_flags | |
152 | member | |
153 | specifies additional options, defined below. | |
154 | Multiple flags are specified by logically OR-ing them together. | |
155 | All the other members in the | |
156 | .I hints | |
157 | parameter must contain either 0, or a null pointer. | |
158 | .PP | |
159 | The | |
160 | .I node | |
161 | or | |
162 | .I service | |
163 | parameter, but not both, may be NULL. | |
164 | .I node | |
165 | specifies either a numerical network address | |
166 | (dotted-decimal format for IPv4, hexadecimal format for IPv6) | |
167 | or a network hostname, whose network addresses are looked up and resolved. | |
168 | If the | |
169 | .I ai_flags | |
170 | member in the | |
171 | .I hints | |
172 | parameter contains the | |
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) | |
183 | function creates a link list of | |
184 | .B addrinfo | |
185 | structures, one for each network address subject to any restrictions | |
186 | imposed by the | |
187 | .I hints | |
188 | parameter. | |
189 | .I ai_canonname | |
190 | is set to point to the official name of the host, if | |
191 | .I ai_flags | |
192 | in | |
193 | .I hints | |
194 | includes the | |
195 | .B AI_CANONNAME | |
196 | flag. | |
197 | .IR ai_family , | |
198 | .IR ai_socktype , | |
199 | and | |
200 | .I ai_protocol | |
201 | specify the socket creation parameters. | |
202 | A pointer to the socket address is placed in the | |
203 | .I ai_addr | |
204 | member, and the length of the socket address, in bytes, | |
205 | is placed in the | |
206 | .I ai_addrlen | |
207 | member. | |
208 | .PP | |
209 | If | |
210 | .I node | |
211 | is NULL, | |
212 | the | |
213 | network address in each socket structure is initialized according to the | |
214 | .B AI_PASSIVE | |
215 | flag, which is set in the | |
216 | .I ai_flags | |
217 | member of the | |
218 | .I hints | |
219 | parameter. | |
220 | The network address in each socket structure will be left unspecified | |
221 | if | |
222 | .B AI_PASSIVE | |
223 | flag is set. | |
224 | This is used by server applications, which intend to accept | |
225 | client connections on any network address. | |
226 | The network address will be set to the loopback interface address | |
227 | if the | |
228 | .B AI_PASSIVE | |
229 | flag is not set. | |
230 | This is used by client applications, which intend to connect | |
231 | to a server running on the same network host. | |
232 | .PP | |
233 | .I service | |
234 | sets the port number in the network address of each socket structure. | |
235 | If | |
236 | .I service | |
237 | is NULL the port number will be left uninitialized. | |
238 | .PP | |
239 | The | |
240 | .BR freeaddrinfo (3) | |
241 | function frees the memory that was allocated | |
242 | for the dynamically allocated link list | |
243 | .IR res . | |
244 | .SH "RETURN VALUE" | |
245 | .BR getaddrinfo (3) | |
246 | returns 0 if it succeeds, or one of the following non-zero error codes: | |
247 | .TP | |
248 | .B EAI_FAMILY | |
249 | The requested address family is not supported at all. | |
250 | .TP | |
251 | .B EAI_SOCKTYPE | |
252 | The requested socket type is not supported at all. | |
253 | .TP | |
254 | .B EAI_BADFLAGS | |
255 | .I ai_flags | |
256 | contains invalid flags. | |
257 | .TP | |
258 | .B EAI_NONAME | |
259 | The | |
260 | .I node | |
261 | or | |
262 | .I service | |
263 | is not known. | |
264 | This error is also returned if both | |
265 | .I node | |
266 | and | |
267 | .I service | |
268 | are NULL. | |
269 | .TP | |
270 | .B EAI_SERVICE | |
271 | The requested service is not available for the requested socket type. | |
272 | It may be available through another socket type. | |
273 | .TP | |
274 | .B EAI_ADDRFAMILY | |
275 | The specified network host does not have any network addresses in the | |
276 | requested address family. | |
277 | .TP | |
278 | .B EAI_NODATA | |
279 | The specified network host exists, but does not have any | |
280 | network addresses defined. | |
281 | .TP | |
282 | .B EAI_MEMORY | |
283 | Out of memory. | |
284 | .TP | |
285 | .B EAI_FAIL | |
286 | The name server returned a permanent failure indication. | |
287 | .TP | |
288 | .B EAI_AGAIN | |
289 | The name server returned a temporary failure indication. | |
290 | Try again later. | |
291 | .TP | |
292 | .B EAI_SYSTEM | |
293 | Other system error, check | |
294 | .I errno | |
295 | for details. | |
296 | .PP | |
297 | The | |
298 | .BR gai_strerror (3) | |
299 | function translates these error codes to a human readable string, | |
300 | suitable for error reporting. | |
301 | .SH "CONFORMING TO" | |
302 | POSIX 1003.1-2003. | |
303 | The | |
304 | .B getaddrinfo() | |
305 | function is documented in RFC 2553. | |
306 | .SH "SEE ALSO" | |
307 | .BR getipnodebyaddr (3), | |
308 | .BR getipnodebyname (3) |