1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3 [<!ENTITY mdash "—">]>
5 - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
6 - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
8 - Permission to use, copy, modify, and/or distribute this software for any
9 - purpose with or without fee is hereby granted, provided that the above
10 - copyright notice and this permission notice appear in all copies.
12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
18 - PERFORMANCE OF THIS SOFTWARE.
25 <date>Jun 30, 2000</date>
29 <refentrytitle>lwres_getaddrinfo</refentrytitle>
30 <manvolnum>3</manvolnum>
31 <refmiscinfo>BIND9</refmiscinfo>
40 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
46 <holder>Internet Software Consortium.</holder>
51 <refname>lwres_getaddrinfo</refname>
52 <refname>lwres_freeaddrinfo</refname>
53 <refpurpose>socket address structure to host and service name</refpurpose>
57 <funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
61 <function>lwres_getaddrinfo</function></funcdef>
62 <paramdef>const char *<parameter>hostname</parameter></paramdef>
63 <paramdef>const char *<parameter>servname</parameter></paramdef>
64 <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>
65 <paramdef>struct addrinfo **<parameter>res</parameter></paramdef>
70 <function>lwres_freeaddrinfo</function></funcdef>
71 <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>
76 If the operating system does not provide a
77 <type>struct addrinfo</type>,
78 the following structure is used:
80 <para><programlisting>
82 int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
83 int ai_family; /* PF_xxx */
84 int ai_socktype; /* SOCK_xxx */
85 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
86 size_t ai_addrlen; /* length of ai_addr */
87 char *ai_canonname; /* canonical name for hostname */
88 struct sockaddr *ai_addr; /* binary address */
89 struct addrinfo *ai_next; /* next structure in linked list */
97 <title>DESCRIPTION</title>
99 <para><function>lwres_getaddrinfo()</function>
100 is used to get a list of IP addresses and port numbers for host
101 <parameter>hostname</parameter> and service
102 <parameter>servname</parameter>.
104 The function is the lightweight resolver's implementation of
105 <function>getaddrinfo()</function> as defined in RFC2133.
106 <parameter>hostname</parameter> and
107 <parameter>servname</parameter> are pointers to null-terminated
108 strings or <type>NULL</type>.
110 <parameter>hostname</parameter> is either a host name or a
111 numeric host address string: a dotted decimal IPv4 address or an
112 IPv6 address. <parameter>servname</parameter> is either a
113 decimal port number or a service name as listed in
114 <filename>/etc/services</filename>.
117 <para><parameter>hints</parameter>
118 is an optional pointer to a
119 <type>struct addrinfo</type>.
120 This structure can be used to provide hints concerning the type of
122 that the caller supports or wishes to use.
123 The caller can supply the following structure elements in
124 <parameter>*hints</parameter>:
128 <term><constant>ai_family</constant></term>
131 The protocol family that should be used.
133 <constant>ai_family</constant>
135 <type>PF_UNSPEC</type>,
136 it means the caller will accept any protocol family supported by
143 <term><constant>ai_socktype</constant></term>
146 denotes the type of socket —
147 <type>SOCK_STREAM</type>,
148 <type>SOCK_DGRAM</type>
150 <type>SOCK_RAW</type>
151 — that is wanted.
153 <constant>ai_socktype</constant>
154 is zero the caller will accept any socket type.
159 <term><constant>ai_protocol</constant></term>
162 indicates which transport protocol is wanted: IPPROTO_UDP or
165 <constant>ai_protocol</constant>
166 is zero the caller will accept any protocol.
171 <term><constant>ai_flags</constant></term>
176 <type>AI_CANONNAME</type>
177 bit is set, a successful call to
178 <function>lwres_getaddrinfo()</function>
179 will return a null-terminated string containing the canonical
181 of the specified hostname in
182 <constant>ai_canonname</constant>
184 <type>addrinfo</type>
187 <type>AI_PASSIVE</type>
188 bit indicates that the returned socket address structure is
190 for used in a call to
192 <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
195 In this case, if the hostname argument is a
197 pointer, then the IP address portion of the socket
198 address structure will be set to
199 <type>INADDR_ANY</type>
200 for an IPv4 address or
201 <type>IN6ADDR_ANY_INIT</type>
206 <constant>ai_flags</constant>
208 <type>AI_PASSIVE</type>
209 bit, the returned socket address structure will be ready
212 <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
214 for a connection-oriented protocol or
216 <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
220 <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
225 <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
227 if a connectionless protocol was chosen.
228 The IP address portion of the socket address structure will be
229 set to the loopback address if
230 <parameter>hostname</parameter>
234 <type>AI_PASSIVE</type>
236 <constant>ai_flags</constant>.
240 <constant>ai_flags</constant>
242 <type>AI_NUMERICHOST</type>
244 <parameter>hostname</parameter>
245 should be treated as a numeric string defining an IPv4 or IPv6
247 and no name resolution should be attempted.
255 All other elements of the <type>struct addrinfo</type> passed
256 via <parameter>hints</parameter> must be zero.
260 A <parameter>hints</parameter> of <type>NULL</type> is
262 the caller provided a <type>struct addrinfo</type> initialized to zero
263 with <constant>ai_family</constant>set to
264 <constant>PF_UNSPEC</constant>.
268 After a successful call to
269 <function>lwres_getaddrinfo()</function>,
270 <parameter>*res</parameter>
271 is a pointer to a linked list of one or more
272 <type>addrinfo</type>
275 <type>struct addrinfo</type>
276 in this list cn be processed by following
278 <constant>ai_next</constant>
281 pointer is encountered.
283 <constant>ai_family</constant>,
284 <constant>ai_socktype</constant>,
286 <constant>ai_protocol</constant>
289 <type>addrinfo</type>
290 structure contain the corresponding arguments for a call to
292 <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
295 <type>addrinfo</type>
296 structure in the list, the
297 <constant>ai_addr</constant>
298 member points to a filled-in socket address structure of length
299 <constant>ai_addrlen</constant>.
303 All of the information returned by
304 <function>lwres_getaddrinfo()</function>
305 is dynamically allocated: the addrinfo structures, and the socket
306 address structures and canonical host name strings pointed to by the
307 <constant>addrinfo</constant>structures.
308 Memory allocated for the dynamically allocated structures created by
310 <function>lwres_getaddrinfo()</function>
312 <function>lwres_freeaddrinfo()</function>.
313 <parameter>ai</parameter>
315 <type>struct addrinfo</type>
317 <function>lwres_getaddrinfo()</function>.
323 <title>RETURN VALUES</title>
325 <para><function>lwres_getaddrinfo()</function>
326 returns zero on success or one of the error codes listed in
328 <refentrytitle>gai_strerror</refentrytitle><manvolnum>3</manvolnum>
330 if an error occurs. If both <parameter>hostname</parameter> and
331 <parameter>servname</parameter> are <type>NULL</type>
332 <function>lwres_getaddrinfo()</function> returns
333 <errorcode>EAI_NONAME</errorcode>.
337 <title>SEE ALSO</title>
339 <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
343 <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
347 <refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
351 <refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
355 <refentrytitle>RFC2133</refentrytitle>
359 <refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
363 <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
367 <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
371 <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
375 <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
379 <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>