1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="TCP/IP Library Reference"
23 HREF="tcpip-library-reference.html"><LINK
26 HREF="net-common-tcpip-manpages-ethers.html"><LINK
29 HREF="net-common-tcpip-manpages-gethostbyname.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="net-common-tcpip-manpages-ethers.html"
65 >Chapter 38. TCP/IP Library Reference</TD
71 HREF="net-common-tcpip-manpages-gethostbyname.html"
85 NAME="NET-COMMON-TCPIP-MANPAGES-GETADDRINFO">getaddrinfo</H1
94 >GETADDRINFO(3) System Library Functions Manual GETADDRINFO(3)
97 getaddrinfo, freeaddrinfo, gai_strerror - nodename-to-address translation
98 in protocol-independent manner
101 #include <sys/types.h>
102 #include <sys/socket.h>
103 #include <netdb.h>
106 getaddrinfo(const char *nodename, const char *servname,
107 const struct addrinfo *hints, struct addrinfo **res);
110 freeaddrinfo(struct addrinfo *ai);
113 gai_strerror(int ecode);
116 The getaddrinfo() function is defined for protocol-independent nodename-
117 to-address translation. It performs the functionality of
118 gethostbyname(3) and getservbyname(3), but in a more sophisticated man-
121 The addrinfo structure is defined as a result of including the <netdb.h>
125 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
126 int ai_family; /* PF_xxx */
127 int ai_socktype; /* SOCK_xxx */
128 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
129 size_t ai_addrlen; /* length of ai_addr */
130 char *ai_canonname; /* canonical name for nodename */
131 struct sockaddr *ai_addr; /* binary address */
132 struct addrinfo *ai_next; /* next structure in linked list */
135 The nodename and servname arguments are pointers to NUL-terminated
136 strings or NULL. One or both of these two arguments must be a non-null
137 pointer. In the normal client scenario, both the nodename and servname
138 are specified. In the normal server scenario, only the servname is spec-
139 ified. A non-null nodename string can be either a node name or a numeric
140 host address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex
141 address). A non-null servname string can be either a service name or a
144 The caller can optionally pass an addrinfo structure, pointed to by the
145 third argument, to provide hints concerning the type of socket that the
146 caller supports. In this hints structure all members other than
147 ai_flags, ai_family, ai_socktype, and ai_protocol must be zero or a null
148 pointer. A value of PF_UNSPEC for ai_family means the caller will accept
149 any protocol family. A value of 0 for ai_socktype means the caller will
150 accept any socket type. A value of 0 for ai_protocol means the caller
151 will accept any protocol. For example, if the caller handles only TCP
152 and not UDP, then the ai_socktype member of the hints structure should be
153 set to SOCK_STREAM when getaddrinfo() is called. If the caller handles
154 only IPv4 and not IPv6, then the ai_family member of the hints structure
155 should be set to PF_INET when getaddrinfo() is called. If the third
156 argument to getaddrinfo() is a null pointer, this is the same as if the
157 caller had filled in an addrinfo structure initialized to zero with
158 ai_family set to PF_UNSPEC.
160 Upon successful return a pointer to a linked list of one or more addrinfo
161 structures is returned through the final argument. The caller can pro-
162 cess each addrinfo structure in this list by following the ai_next
163 pointer, until a null pointer is encountered. In each returned addrinfo
164 structure the three members ai_family, ai_socktype, and ai_protocol are
165 the corresponding arguments for a call to the socket() function. In each
166 addrinfo structure the ai_addr member points to a filled-in socket
167 address structure whose length is specified by the ai_addrlen member.
169 If the AI_PASSIVE bit is set in the ai_flags member of the hints struc-
170 ture, then the caller plans to use the returned socket address structure
171 in a call to bind(). In this case, if the nodename argument is a null
172 pointer, then the IP address portion of the socket address structure will
173 be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
176 If the AI_PASSIVE bit is not set in the ai_flags member of the hints
177 structure, then the returned socket address structure will be ready for a
178 call to connect() (for a connection-oriented protocol) or either
179 connect(), sendto(), or sendmsg() (for a connectionless protocol). In
180 this case, if the nodename argument is a null pointer, then the IP
181 address portion of the socket address structure will be set to the loop-
184 If the AI_CANONNAME bit is set in the ai_flags member of the hints struc-
185 ture, then upon successful return the ai_canonname member of the first
186 addrinfo structure in the linked list will point to a NUL-terminated
187 string containing the canonical name of the specified nodename.
189 If the AI_NUMERICHOST bit is set in the ai_flags member of the hints
190 structure, then a non-null nodename string must be a numeric host address
191 string. Otherwise an error of EAI_NONAME is returned. This flag pre-
192 vents any type of name resolution service (e.g., the DNS) from being
195 The arguments to getaddrinfo() must sufficiently be consistent and unam-
196 biguous. Here are pitfall cases you may encounter:
198 o getaddrinfo() will raise an error if members of the hints structure
199 are not consistent. For example, for internet address families,
200 getaddrinfo() will raise an error if you specify SOCK_STREAM to
201 ai_socktype while you specify IPPROTO_UDP to ai_protocol.
203 o If you specify a servname which is defined only for certain
204 ai_socktype, getaddrinfo() will raise an error because the arguments
205 are not consistent. For example, getaddrinfo() will raise an error
206 if you ask for ``tftp'' service on SOCK_STREAM.
208 o For internet address families, if you specify servname while you set
209 ai_socktype to SOCK_RAW, getaddrinfo() will raise an error, because
210 service names are not defined for the internet SOCK_RAW space.
212 o If you specify a numeric servname, while leaving ai_socktype and
213 ai_protocol unspecified, getaddrinfo() will raise an error. This is
214 because the numeric servname does not identify any socket type, and
215 getaddrinfo() is not allowed to glob the argument in such case.
217 All of the information returned by getaddrinfo() is dynamically allo-
218 cated: the addrinfo structures, the socket address structures, and canon-
219 ical node name strings pointed to by the addrinfo structures. To return
220 this information to the system the function freeaddrinfo() is called.
221 The addrinfo structure pointed to by the ai argument is freed, along with
222 any dynamic storage pointed to by the structure. This operation is
223 repeated until a NULL ai_next pointer is encountered.
225 To aid applications in printing error messages based on the EAI_xxx codes
226 returned by getaddrinfo(), gai_strerror() is defined. The argument is
227 one of the EAI_xxx values defined earlier and the return value points to
228 a string describing the error. If the argument is not one of the EAI_xxx
229 values, the function still returns a pointer to a string whose contents
230 indicate an unknown error.
232 Extension for scoped IPv6 address
233 The implementation allows experimental numeric IPv6 address notation with
234 scope identifier. By appending the percent character and scope identi-
235 fier to addresses, you can fill sin6_scope_id field for addresses. This
236 would make management of scoped address easier, and allows cut-and-paste
237 input of scoped address.
239 At this moment the code supports only link-local addresses with the for-
240 mat. Scope identifier is hardcoded to name of hardware interface associ-
241 ated with the link. (such as ne0). Example would be like
242 ``fe80::1%ne0'', which means ``fe80::1 on the link associated with ne0
245 The implementation is still very experimental and non-standard. The cur-
246 rent implementation assumes one-by-one relationship between interface and
247 link, which is not necessarily true from the specification.
250 The following code tries to connect to ``www.kame.net'' service ``http''.
251 via stream socket. It loops through all the addresses available, regard-
252 less from address family. If the destination resolves to IPv4 address,
253 it will use AF_INET socket. Similarly, if it resolves to IPv6, AF_INET6
254 socket is used. Observe that there is no hardcoded reference to particu-
255 lar address family. The code works even if getaddrinfo returns addresses
256 that are not IPv4/v6.
258 struct addrinfo hints, *res, *res0;
261 const char *cause = NULL;
263 memset(&hints, 0, sizeof(hints));
264 hints.ai_family = PF_UNSPEC;
265 hints.ai_socktype = SOCK_STREAM;
266 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
268 errx(1, "%s", gai_strerror(error));
272 for (res = res0; res; res = res->ai_next) {
273 s = socket(res->ai_family, res->ai_socktype,
274 res->ai_protocol);
280 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
287 break; /* okay we got one */
295 The following example tries to open a wildcard listening socket onto ser-
296 vice ``http'', for all the address families available.
298 struct addrinfo hints, *res, *res0;
302 const char *cause = NULL;
304 memset(&hints, 0, sizeof(hints));
305 hints.ai_family = PF_UNSPEC;
306 hints.ai_socktype = SOCK_STREAM;
307 hints.ai_flags = AI_PASSIVE;
308 error = getaddrinfo(NULL, "http", &hints, &res0);
310 errx(1, "%s", gai_strerror(error));
314 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
315 s[nsock] = socket(res->ai_family, res->ai_socktype,
316 res->ai_protocol);
317 if (s[nsock] < 0) {
322 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
327 (void) listen(s[nsock], 5);
338 Error return status from getaddrinfo() is zero on success and non-zero on
339 errors. Non-zero error codes are defined in <netdb.h>, and as follows:
341 EAI_ADDRFAMILY Address family for nodename not supported.
342 EAI_AGAIN Temporary failure in name resolution.
343 EAI_BADFLAGS Invalid value for ai_flags.
344 EAI_FAIL Non-recoverable failure in name resolution.
345 EAI_FAMILY ai_family not supported.
346 EAI_MEMORY Memory allocation failure.
347 EAI_NODATA No address associated with nodename.
348 EAI_NONAME nodename nor servname provided, or not known.
349 EAI_SERVICE servname not supported for ai_socktype.
350 EAI_SOCKTYPE ai_socktype not supported.
351 EAI_SYSTEM System error returned in errno.
353 If called with proper argument, gai_strerror() returns a pointer to a
354 string describing the given error code. If the argument is not one of
355 the EAI_xxx values, the function still returns a pointer to a string
356 whose contents indicate an unknown error.
359 getnameinfo(3), gethostbyname(3), getservbyname(3), hosts(5),
360 resolv.conf(5), services(5), hostname(7), named(8)
362 R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
363 Extensions for IPv6, RFC2553, March 1999.
365 Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
366 Addresses, internet draft, draft-ietf-ipngwg-scopedaddr-format-02.txt,
367 work in progress material.
369 Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
370 the freenix track: 2000 USENIX annual technical conference, June 2000.
373 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
377 The getaddrinfo() function is defined in IEEE POSIX 1003.1g draft speci-
378 fication, and documented in ``Basic Socket Interface Extensions for
382 The current implementation is not thread-safe.
384 The text was shamelessly copied from RFC2553.
397 SUMMARY="Footer navigation table"
408 HREF="net-common-tcpip-manpages-ethers.html"
426 HREF="net-common-tcpip-manpages-gethostbyname.html"
442 HREF="tcpip-library-reference.html"