| blob | 47d55095e9d4b80bcde11d1299f637f57be0ba27 |
1 .\" $NetBSD$
2 .\"
3 .\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC")
4 .\"
5 .\" Permission to use, copy, modify, and/or distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 .\" PERFORMANCE OF THIS SOFTWARE.
16 .\"
17 .\" Id: getaddrinfo.3,v 1.3 2009/01/22 23:49:23 tbox Exp
18 .\"
19 .Dd May 25, 1995
20 .Dt GETADDRINFO @LIB_NETWORK_EXT@
21 .Os KAME
22 .Sh NAME
23 .Nm getaddrinfo
24 .Nm freeaddrinfo ,
25 .Nm gai_strerror
26 .Nd nodename-to-address translation in protocol-independent manner
27 .Sh SYNOPSIS
28 .Fd #include <sys/socket.h>
29 .Fd #include <netdb.h>
30 .Ft int
31 .Fn getaddrinfo "const char *nodename" "const char *servname" \
32 "const struct addrinfo *hints" "struct addrinfo **res"
33 .Ft void
34 .Fn freeaddrinfo "struct addrinfo *ai"
35 .Ft "char *"
36 .Fn gai_strerror "int ecode"
37 .Sh DESCRIPTION
38 The
39 .Fn getaddrinfo
40 function is defined for protocol-independent nodename-to-address translation.
41 It performs functionality of
42 .Xr gethostbyname @LIB_NETWORK_EXT@
43 and
44 .Xr getservbyname @LIB_NETWORK_EXT@ ,
45 in more sophisticated manner.
46 .Pp
47 The addrinfo structure is defined as a result of including the
48 .Li <netdb.h>
49 header:
50 .Bd -literal -offset
51 struct addrinfo { *
52 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
53 int ai_family; /* PF_xxx */
54 int ai_socktype; /* SOCK_xxx */
55 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
56 size_t ai_addrlen; /* length of ai_addr */
57 char *ai_canonname; /* canonical name for nodename */
58 struct sockaddr *ai_addr; /* binary address */
59 struct addrinfo *ai_next; /* next structure in linked list */
60 };
61 .Ed
62 .Pp
63 The
64 .Fa nodename
65 and
66 .Fa servname
67 arguments are pointers to null-terminated strings or
68 .Dv NULL .
69 One or both of these two arguments must be a
70 .Pf non Dv -NULL
71 pointer.
72 In the normal client scenario, both the
73 .Fa nodename
74 and
75 .Fa servname
76 are specified.
77 In the normal server scenario, only the
78 .Fa servname
79 is specified.
80 A
81 .Pf non Dv -NULL
82 .Fa nodename
83 string can be either a node name or a numeric host address string
84 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
85 A
86 .Pf non Dv -NULL
87 .Fa servname
88 string can be either a service name or a decimal port number.
89 .Pp
90 The caller can optionally pass an
91 .Li addrinfo
92 structure, pointed to by the third argument,
93 to provide hints concerning the type of socket that the caller supports.
94 In this
95 .Fa hints
96 structure all members other than
97 .Fa ai_flags ,
98 .Fa ai_family ,
99 .Fa ai_socktype ,
100 and
101 .Fa ai_protocol
102 must be zero or a
103 .Dv NULL
104 pointer.
105 A value of
106 .Dv PF_UNSPEC
107 for
108 .Fa ai_family
109 means the caller will accept any protocol family.
110 A value of 0 for
111 .Fa ai_socktype
112 means the caller will accept any socket type.
113 A value of 0 for
114 .Fa ai_protocol
115 means the caller will accept any protocol.
116 For example, if the caller handles only TCP and not UDP, then the
117 .Fa ai_socktype
118 member of the hints structure should be set to
119 .Dv SOCK_STREAM
120 when
121 .Fn getaddrinfo
122 is called.
123 If the caller handles only IPv4 and not IPv6, then the
124 .Fa ai_family
125 member of the
126 .Fa hints
127 structure should be set to
128 .Dv PF_INET
129 when
130 .Fn getaddrinfo
131 is called.
132 If the third argument to
133 .Fn getaddrinfo
134 is a
135 .Dv NULL
136 pointer, this is the same as if the caller had filled in an
137 .Li addrinfo
138 structure initialized to zero with
139 .Fa ai_family
140 set to PF_UNSPEC.
141 .Pp
142 Upon successful return a pointer to a linked list of one or more
143 .Li addrinfo
144 structures is returned through the final argument.
145 The caller can process each
146 .Li addrinfo
147 structure in this list by following the
148 .Fa ai_next
149 pointer, until a
150 .Dv NULL
151 pointer is encountered.
152 In each returned
153 .Li addrinfo
154 structure the three members
155 .Fa ai_family ,
156 .Fa ai_socktype ,
157 and
158 .Fa ai_protocol
159 are the corresponding arguments for a call to the
160 .Fn socket
161 function.
162 In each
163 .Li addrinfo
164 structure the
165 .Fa ai_addr
166 member points to a filled-in socket address structure whose length is
167 specified by the
168 .Fa ai_addrlen
169 member.
170 .Pp
171 If the
172 .Dv AI_PASSIVE
173 bit is set in the
174 .Fa ai_flags
175 member of the
176 .Fa hints
177 structure, then the caller plans to use the returned socket address
178 structure in a call to
179 .Fn bind .
180 In this case, if the
181 .Fa nodename
182 argument is a
183 .Dv NULL
184 pointer, then the IP address portion of the socket
185 address structure will be set to
186 .Dv INADDR_ANY
187 for an IPv4 address or
188 .Dv IN6ADDR_ANY_INIT
189 for an IPv6 address.
190 .Pp
191 If the
192 .Dv AI_PASSIVE
193 bit is not set in the
194 .Fa ai_flags
195 member of the
196 .Fa hints
197 structure, then the returned socket address structure will be ready for a
198 call to
199 .Fn connect
200 .Pq for a connection-oriented protocol
201 or either
202 .Fn connect ,
203 .Fn sendto ,
204 or
205 .Fn sendmsg
206 .Pq for a connectionless protocol .
207 In this case, if the
208 .Fa nodename
209 argument is a
210 .Dv NULL
211 pointer, then the IP address portion of the
212 socket address structure will be set to the loopback address.
213 .Pp
214 If the
215 .Dv AI_CANONNAME
216 bit is set in the
217 .Fa ai_flags
218 member of the
219 .Fa hints
220 structure, then upon successful return the
221 .Fa ai_canonname
222 member of the first
223 .Li addrinfo
224 structure in the linked list will point to a null-terminated string
225 containing the canonical name of the specified
226 .Fa nodename .
227 .Pp
228 If the
229 .Dv AI_NUMERICHOST
230 bit is set in the
231 .Fa ai_flags
232 member of the
233 .Fa hints
234 structure, then a
235 .Pf non Dv -NULL
236 .Fa nodename
237 string must be a numeric host address string.
238 Otherwise an error of
239 .Dv EAI_NONAME
240 is returned.
241 This flag prevents any type of name resolution service (e.g., the DNS)
242 from being called.
243 .Pp
244 All of the information returned by
245 .Fn getaddrinfo
246 is dynamically allocated:
247 the
248 .Li addrinfo
249 structures, and the socket address structures and canonical node name
250 strings pointed to by the addrinfo structures.
251 To return this information to the system the function
252 Fn freeaddrinfo
253 is called.
254 The
255 .Fa addrinfo
256 structure pointed to by the
257 .Fa ai argument
258 is freed, along with any dynamic storage pointed to by the structure.
259 This operation is repeated until a
260 .Dv NULL
261 .Fa ai_next
262 pointer is encountered.
263 .Pp
264 To aid applications in printing error messages based on the
265 .Dv EAI_xxx
266 codes returned by
267 .Fn getaddrinfo ,
268 .Fn gai_strerror
269 is defined.
270 The argument is one of the
271 .Dv EAI_xxx
272 values defined earlier and the return value points to a string describing
273 the error.
274 If the argument is not one of the
275 .Dv EAI_xxx
276 values, the function still returns a pointer to a string whose contents
277 indicate an unknown error.
278 .Sh FILES
279 .Bl -tag -width /etc/resolv.conf -compact
280 .It Pa /etc/hosts
281 .It Pa /etc/host.conf
282 .It Pa /etc/resolv.conf
283 .El
284 .Sh DIAGNOSTICS
285 Error return status from
286 .Fn getaddrinfo
287 is zero on success and non-zero on errors.
288 Non-zero error codes are defined in
289 .Li <netdb.h> ,
290 and as follows:
291 .Pp
292 .Bl -tag -width EAI_ADDRFAMILY -compact
293 .It Dv EAI_ADDRFAMILY
294 address family for nodename not supported
295 .It Dv EAI_AGAIN
296 temporary failure in name resolution
297 .It Dv EAI_BADFLAGS
298 invalid value for ai_flags
299 .It Dv EAI_FAIL
300 non-recoverable failure in name resolution
301 .It Dv EAI_FAMILY
302 ai_family not supported
303 .It Dv EAI_MEMORY
304 memory allocation failure
305 .It Dv EAI_NODATA
306 no address associated with nodename
307 .It Dv EAI_NONAME
308 nodename nor servname provided, or not known
309 .It Dv EAI_SERVICE
310 servname not supported for ai_socktype
311 .It Dv EAI_SOCKTYPE
312 ai_socktype not supported
313 .It Dv EAI_SYSTEM
314 system error returned in errno
315 .El
316 .Pp
317 If called with proper argument,
318 .Fn gai_strerror
319 returns a pointer to a string describing the given error code.
320 If the argument is not one of the
321 .Dv EAI_xxx
322 values, the function still returns a pointer to a string whose contents
323 indicate an unknown error.
324 .Sh SEE ALSO
325 .Xr getnameinfo @LIB_NETWORK_EXT@ ,
326 .Xr gethostbyname @LIB_NETWORK_EXT@ ,
327 .Xr getservbyname @LIB_NETWORK_EXT@ ,
328 .Xr hosts @FORMAT_EXT@ ,
329 .Xr services @FORMAT_EXT@ ,
330 .Xr hostname @DESC_EXT@
331 .Pp
332 R. Gilligan, S. Thomson, J. Bound, and W. Stevens,
333 ``Basic Socket Interface Extensions for IPv6,'' RFC2133, April 1997.
334 .Sh HISTORY
335 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
336 .Sh STANDARDS
337 The
338 .Fn getaddrinfo
339 function is defined IEEE POSIX 1003.1g draft specification,
340 and documented in ``Basic Socket Interface Extensions for IPv6''
341 (RFC2133).
342 .Sh BUGS
343 The text was shamelessly copied from RFC2133.