Penguin
Recent Changes
Blame: freeaddrinfo(3)
EditPageHistoryDiffInfoLikePages
Annotated edit history of freeaddrinfo(3) version 4, including all changes. View license author blame.
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
4 perry 217 The gai_strerror(3) function translates these error
1 perry 218 codes to a human readable string, suitable for error
219 reporting.
220 !!SEE ALSO
221
222
223 getipnodebyname(3),
224 getipnodebyaddr(3)
225 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.