version 4 showing authors affecting page license.
.
Rev |
Author |
# |
Line |
1 |
perry |
1 |
getaddrinfo |
|
|
2 |
!!!getaddrinfo |
|
|
3 |
NAME |
|
|
4 |
SYNOPSIS |
|
|
5 |
DESCRIPTION |
|
|
6 |
RETURN VALUE |
|
|
7 |
SEE ALSO |
|
|
8 |
---- |
|
|
9 |
!!NAME |
|
|
10 |
|
|
|
11 |
|
|
|
12 |
getaddrinfo - network address and service translation |
|
|
13 |
!!SYNOPSIS |
|
|
14 |
|
|
|
15 |
|
|
|
16 |
__#include |
|
|
17 |
__''node''__, const char *__''service''__, |
|
|
18 |
const struct addrinfo *__''hints''__, |
|
|
19 |
struct addrinfo **__''res''__); |
|
|
20 |
void freeaddrinfo(struct addrinfo *__''res''__); |
|
|
21 |
const char *gai_strerror(int__ ''errcode''__); |
|
|
22 |
__ |
|
|
23 |
!!DESCRIPTION |
|
|
24 |
|
|
|
25 |
|
|
|
26 |
The getaddrinfo(3) function combines the |
|
|
27 |
functionality provided by the getipnodebyname(3), |
|
|
28 |
getipnodebyaddr(3), getservbyname(3), and |
|
|
29 |
getservbyport(3) functions into a single interface. |
|
|
30 |
The thread-safe getaddrinfo(3) function creates one |
|
|
31 |
or more socket address structures that can be used by the |
|
|
32 |
bind(2) and connect(2) system calls to create |
|
|
33 |
a client or a server socket. |
|
|
34 |
|
|
|
35 |
|
|
|
36 |
The getaddrinfo(3) function is not limited to |
|
|
37 |
creating IPv4 socket address structures; IPv6 socket address |
|
|
38 |
structures can be created if IPv6 support is available. |
|
|
39 |
These socket address structures can be used directly by |
|
|
40 |
bind(2) or connect(2), to prepare a client or |
|
|
41 |
a server socket. |
|
|
42 |
|
|
|
43 |
|
|
|
44 |
The __addrinfo__ structure used by this function contains |
|
|
45 |
the following members: |
|
|
46 |
|
|
|
47 |
|
|
|
48 |
__struct addrinfo { |
|
|
49 |
int__ '' ai_flags''__; |
|
|
50 |
int__ '' ai_family''__; |
|
|
51 |
int__ '' ai_socktype''__; |
|
|
52 |
int__ '' ai_protocol''__; |
|
|
53 |
size_t__ '' ai_addrlen''__; |
|
|
54 |
struct sockaddr *__''ai_addr''__; |
|
|
55 |
char *__''ai_canonname''__; |
|
|
56 |
struct addrinfo *__''ai_next''__; |
|
|
57 |
}; |
|
|
58 |
__getaddrinfo(3) sets ''res'' to point to a dynamically-allocated link list of __addrinfo__ structures, linked by the ''ai_next'' member. There are several reasons why the link list may have more than one __addrinfo__ structure, including: if the network host is multi-homed; or if the same service is available from multiple socket protocols (one __SOCK_STREAM__ address and another __SOCK_DGRAM__ address, for example). |
|
|
59 |
|
|
|
60 |
|
|
|
61 |
The members ''ai_family'', ''ai_socktype'', and |
|
|
62 |
''ai_protocol'' have the same meaning as the |
|
|
63 |
corresponding parameters in the socket(2) system |
|
|
64 |
call. The getaddrinfo(3) function returns socket |
|
|
65 |
addresses in either IPv4 or IPv6 address family, |
|
|
66 |
(''ai_family'' will be set to either __PF_INET__ or |
|
|
67 |
__PF_INET6__). |
|
|
68 |
|
|
|
69 |
|
|
|
70 |
The ''hints'' parameter specifies the preferred socket |
|
|
71 |
type, or protocol. A NULL ''hints'' specifies that any |
|
|
72 |
network address or protocol is acceptable. If this parameter |
|
|
73 |
is not __NULL__ it points to an __addrinfo__ structure |
|
|
74 |
whose ''ai_family'', ''ai_socktype'', and |
|
|
75 |
''ai_protocol'' members specify the preferred socket |
|
|
76 |
type. __PF_UNSPEC__ in ''ai_family'' specifies any |
|
|
77 |
protocol family (either IPv4 or IPv6, for example). 0 in |
|
|
78 |
''ai_socktype'' or ''ai_protocol'' specifies that any |
|
|
79 |
socket type or protocol is acceptable as well. The |
|
|
80 |
''ai_flags'' member specifies additional options, defined |
|
|
81 |
below. Multiple flags are specified by logically OR-ing them |
|
|
82 |
together. All the other members in the ''hints'' |
|
|
83 |
parameter must contain either 0, or a null |
|
|
84 |
pointer. |
|
|
85 |
|
|
|
86 |
|
|
|
87 |
The ''node'' or ''service'' parameter, but not both, |
|
|
88 |
may be NULL. ''node'' specifies either a numerical |
|
|
89 |
network address (dotted-decimal format for IPv4, hexadecimal |
|
|
90 |
format for IPv6) or a network hostname, whose network |
|
|
91 |
addresses are looked up and resolved. If the ''ai_flags'' |
|
|
92 |
member in the ''hints'' parameter contains the |
|
|
93 |
__AI_NUMERICHOST__ flag then the ''node'' parameter |
|
|
94 |
must be a numerical network address. The |
|
|
95 |
__AI_NUMERICHOST__ flag suppresses any potentially |
|
|
96 |
lengthy network host address lookups. |
|
|
97 |
|
|
|
98 |
|
|
|
99 |
The getaddrinfo(3) function creates a link list of |
|
|
100 |
__addrinfo__ structures, one for each network address |
|
|
101 |
subject to any restrictions imposed by the ''hints'' |
|
|
102 |
parameter. ''ai_canonname'' is set to point to the |
|
|
103 |
official name of the host, if ''ai_flags'' in |
|
|
104 |
''hints'' includes the __AI_CANONNAME__ flag. |
|
|
105 |
''ai_family'', ''ai_socktype'', and ''ai_protocol'' |
|
|
106 |
specify the socket creation parameters. A pointer to the |
|
|
107 |
socket address is placed in the ''ai_addr'' member, and |
|
|
108 |
the length of the socket address, in bytes, is placed in the |
|
|
109 |
''ai_addrlen'' member. |
|
|
110 |
|
|
|
111 |
|
|
|
112 |
If ''node'' is NULL, the network address in each socket |
|
|
113 |
structure is initialized according to the __AI_PASSIVE__ |
|
|
114 |
flag, which is set in the ''ai_flags'' member of the |
|
|
115 |
''hints'' parameter. The network address in each socket |
|
|
116 |
structure will be left unspecified if __AI_PASSIVE__ flag |
|
|
117 |
is set. This is used by server applications, which intend to |
|
|
118 |
accept client connections on any network address. The |
|
|
119 |
network address will be set to the loopback interface |
|
|
120 |
address if the __AI_PASSIVE__ flag is not set. This is |
|
|
121 |
used by client applications, which intend to connect to a |
|
|
122 |
server running on the same network host. |
|
|
123 |
|
|
|
124 |
|
|
|
125 |
''service'' sets the port number in the network address |
|
|
126 |
of each socket structure. If ''service'' is NULL the port |
|
|
127 |
number will be left uninitialized. |
|
|
128 |
|
|
|
129 |
|
|
|
130 |
The freeaddrinfo(3) function frees the memory that |
|
|
131 |
was allocated for the dynamically allocated link list |
|
|
132 |
''res''. |
|
|
133 |
!!RETURN VALUE |
|
|
134 |
|
|
|
135 |
|
|
|
136 |
getaddrinfo(3) returns 0 if it succeeds, or one of |
|
|
137 |
the following non-zero error codes: |
|
|
138 |
|
|
|
139 |
|
|
|
140 |
__EAI_FAMILY__ |
|
|
141 |
|
|
|
142 |
|
|
|
143 |
The requested address family is not supported at |
|
|
144 |
all. |
|
|
145 |
|
|
|
146 |
|
|
|
147 |
__EAI_SOCKTYPE__ |
|
|
148 |
|
|
|
149 |
|
|
|
150 |
The requested socket type is not supported at |
|
|
151 |
all. |
|
|
152 |
|
|
|
153 |
|
|
|
154 |
__EAI_BADFLAGS__ |
|
|
155 |
|
|
|
156 |
|
|
|
157 |
''ai_flags'' contains invalid flags. |
|
|
158 |
|
|
|
159 |
|
|
|
160 |
__EAI_NONAME__ |
|
|
161 |
|
|
|
162 |
|
|
|
163 |
The ''node'' or ''service'' is not known. This error |
|
|
164 |
is also returned if both ''node'' and ''service'' are |
|
|
165 |
NULL. |
|
|
166 |
|
|
|
167 |
|
|
|
168 |
__EAI_SERVICE__ |
|
|
169 |
|
|
|
170 |
|
|
|
171 |
The requested service is not available for the requested |
|
|
172 |
socket type. It may be available through another socket |
|
|
173 |
type. |
|
|
174 |
|
|
|
175 |
|
|
|
176 |
__EAI_ADDRFAMILY__ |
|
|
177 |
|
|
|
178 |
|
|
|
179 |
The specified network host does not have any network |
|
|
180 |
addresses in the requested address family. |
|
|
181 |
|
|
|
182 |
|
|
|
183 |
__EAI_NODATA__ |
|
|
184 |
|
|
|
185 |
|
|
|
186 |
The specified network host exists, but does not have any |
|
|
187 |
network addresses defined. |
|
|
188 |
|
|
|
189 |
|
|
|
190 |
__EAI_MEMORY__ |
|
|
191 |
|
|
|
192 |
|
|
|
193 |
Out of memory. |
|
|
194 |
|
|
|
195 |
|
|
|
196 |
__EAI_FAIL__ |
|
|
197 |
|
|
|
198 |
|
|
|
199 |
The name server returned a permanent failure |
|
|
200 |
indication. |
|
|
201 |
|
|
|
202 |
|
|
|
203 |
__EAI_AGAIN__ |
|
|
204 |
|
|
|
205 |
|
|
|
206 |
The name server returned a temporary failure indication. Try |
|
|
207 |
again later. |
|
|
208 |
|
|
|
209 |
|
|
|
210 |
__EAI_SYSTEM__ |
|
|
211 |
|
|
|
212 |
|
|
|
213 |
Other system error, check ''errno'' for |
|
|
214 |
details. |
|
|
215 |
|
|
|
216 |
|
|
|
217 |
The gai_strerror(3) function translates these error |
|
|
218 |
codes to a human readable string, suitable for error |
|
|
219 |
reporting. |
|
|
220 |
!!SEE ALSO |
|
|
221 |
|
|
|
222 |
|
|
|
223 |
getipnodebyname(3), |
|
|
224 |
getipnodebyaddr(3) |
|
|
225 |
---- |