Merge from vendor branch TNFTP:
[dragonfly.git] / contrib / bind-9.3 / lib / lwres / man / lwres_getaddrinfo.html
1 <!--
2  - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
3  - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
4  - 
5  - Permission to use, copy, modify, and 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: lwres_getaddrinfo.html,v 1.8.2.1.4.12 2006/06/29 13:02:31 marka Exp $ -->
18 <html>
19 <head>
20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
21 <title>lwres_getaddrinfo</title>
22 <meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
23 </head>
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="id2482688"></a><div class="titlepage"></div>
26 <div class="refnamediv">
27 <h2>Name</h2>
28 <p>lwres_getaddrinfo, lwres_freeaddrinfo &#8212; socket address structure to host and service name</p>
29 </div>
30 <div class="refsynopsisdiv">
31 <h2>Synopsis</h2>
32 <div class="funcsynopsis">
33 <pre class="funcsynopsisinfo">#include &lt;lwres/netdb.h&gt;</pre>
34 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
35 <tr>
36 <td><code class="funcdef">
37 int
38 <b class="fsfunc">lwres_getaddrinfo</b>(</code></td>
39 <td> </td>
40 <td>, </td>
41 </tr>
42 <tr>
43 <td> </td>
44 <td> </td>
45 <td>, </td>
46 </tr>
47 <tr>
48 <td> </td>
49 <td> </td>
50 <td>, </td>
51 </tr>
52 <tr>
53 <td> </td>
54 <td> </td>
55 <td>, </td>
56 </tr>
57 <tr>
58 <td> </td>
59 <td> </td>
60 <td>
61 <code>)</code>;</td>
62 </tr>
63 </table>
64 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
65 <tr>
66 <td><code class="funcdef">
67 void
68 <b class="fsfunc">lwres_freeaddrinfo</b>(</code></td>
69 <td> </td>
70 <td>
71 <code>)</code>;</td>
72 </tr>
73 <tr>
74 <td> </td>
75 <td> </td>
76 <td>
77 <code>)</code>;</td>
78 </tr>
79 </table>
80 </div>
81 <p>
82 If the operating system does not provide a
83 <span class="type">struct addrinfo</span>,
84 the following structure is used:
85
86 </p>
87 <pre class="programlisting">
88 struct  addrinfo {
89         int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
90         int             ai_family;      /* PF_xxx */
91         int             ai_socktype;    /* SOCK_xxx */
92         int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
93         size_t          ai_addrlen;     /* length of ai_addr */
94         char            *ai_canonname;  /* canonical name for hostname */
95         struct sockaddr *ai_addr;       /* binary address */
96         struct addrinfo *ai_next;       /* next structure in linked list */
97 };
98 </pre>
99 <p>
100 </p>
101 </div>
102 <div class="refsect1" lang="en">
103 <a name="id2549448"></a><h2>DESCRIPTION</h2>
104 <p>
105 <code class="function">lwres_getaddrinfo()</code>
106 is used to get a list of IP addresses and port numbers for host
107 <em class="parameter"><code>hostname</code></em>
108 and service
109 <em class="parameter"><code>servname</code></em>.
110
111 The function is the lightweight resolver's implementation of
112 <code class="function">getaddrinfo()</code>
113 as defined in RFC2133.
114 <em class="parameter"><code>hostname</code></em>
115 and
116 <em class="parameter"><code>servname</code></em>
117 are pointers to null-terminated
118 strings or
119 <span class="type">NULL</span>.
120
121 <em class="parameter"><code>hostname</code></em>
122 is either a host name or a numeric host address string: a dotted decimal
123 IPv4 address or an IPv6 address.
124 <em class="parameter"><code>servname</code></em>
125 is either a decimal port number or a service name as listed in
126 <code class="filename">/etc/services</code>.
127 </p>
128 <p>
129 <em class="parameter"><code>hints</code></em>
130 is an optional pointer to a
131 <span class="type">struct addrinfo</span>.
132 This structure can be used to provide hints concerning the type of socket
133 that the caller supports or wishes to use.
134 The caller can supply the following structure elements in
135 <em class="parameter"><code>*hints</code></em>:
136
137 </p>
138 <div class="variablelist"><dl>
139 <dt><span class="term"><code class="constant">ai_family</code></span></dt>
140 <dd><p>The protocol family that should be used.
141 When
142 <code class="constant">ai_family</code>
143 is set to
144 <span class="type">PF_UNSPEC</span>,
145 it means the caller will accept any protocol family supported by the
146 operating system.
147 </p></dd>
148 <dt><span class="term"><code class="constant">ai_socktype</code></span></dt>
149 <dd><p>
150 denotes the type of socket &#8212;
151 <span class="type">SOCK_STREAM</span>,
152 <span class="type">SOCK_DGRAM</span>
153 or
154 <span class="type">SOCK_RAW</span>
155 &#8212; that is wanted.
156 When
157 <code class="constant">ai_socktype</code>
158 is zero the caller will accept any socket type.
159 </p></dd>
160 <dt><span class="term"><code class="constant">ai_protocol</code></span></dt>
161 <dd><p>
162 indicates which transport protocol is wanted: IPPROTO_UDP or 
163 IPPROTO_TCP.
164 If
165 <code class="constant">ai_protocol</code>
166 is zero the caller will accept any protocol.
167 </p></dd>
168 <dt><span class="term"><code class="constant">ai_flags</code></span></dt>
169 <dd>
170 <p>
171 Flag bits.
172 If the
173 <span class="type">AI_CANONNAME</span>
174 bit is set, a successful call to
175 <code class="function">lwres_getaddrinfo()</code>
176 will return a null-terminated string containing the canonical name
177 of the specified hostname in
178 <code class="constant">ai_canonname</code>
179 of the first
180 <span class="type">addrinfo</span>
181 structure returned.
182 Setting the
183 <span class="type">AI_PASSIVE</span>
184 bit indicates that the returned socket address structure is intended
185 for used in a call to
186 <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>.
187
188 In this case, if the hostname argument is a
189 <span class="type">NULL</span>
190 pointer, then the IP address portion of the socket
191 address structure will be set to
192 <span class="type">INADDR_ANY</span>
193 for an IPv4 address or
194 <span class="type">IN6ADDR_ANY_INIT</span>
195 for an IPv6 address.
196 </p>
197 <p>
198 When
199 <code class="constant">ai_flags</code>
200 does not set the
201 <span class="type">AI_PASSIVE</span>
202 bit, the returned socket address structure will be ready
203 for use in a call to
204 <span class="citerefentry"><span class="refentrytitle">connect</span>(2
205 )</span>
206 for a connection-oriented protocol or
207 <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>,
208
209 <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>,
210
211 or
212 <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2
213 )</span>
214 if a connectionless protocol was chosen.
215 The IP address portion of the socket address structure will be
216 set to the loopback address if
217 <em class="parameter"><code>hostname</code></em>
218 is a
219 <span class="type">NULL</span>
220 pointer and
221 <span class="type">AI_PASSIVE</span>
222 is not set in
223 <code class="constant">ai_flags</code>.
224 </p>
225 <p>
226 If
227 <code class="constant">ai_flags</code>
228 is set to
229 <span class="type">AI_NUMERICHOST</span>
230 it indicates that
231 <em class="parameter"><code>hostname</code></em>
232 should be treated as a numeric string defining an IPv4 or IPv6 address
233 and no name resolution should be attempted.
234 </p>
235 </dd>
236 </dl></div>
237 <p>
238 </p>
239 <p>
240 All other elements of the <span class="type">struct addrinfo</span> passed
241 via <em class="parameter"><code>hints</code></em> must be zero.
242 </p>
243 <p>
244 A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is treated as if
245 the caller provided a <span class="type">struct addrinfo</span> initialized to zero
246 with <code class="constant">ai_family</code>set to
247 <code class="constant">PF_UNSPEC</code>.
248 </p>
249 <p>
250 After a successful call to
251 <code class="function">lwres_getaddrinfo()</code>,
252 <em class="parameter"><code>*res</code></em>
253 is a pointer to a linked list of one or more
254 <span class="type">addrinfo</span>
255 structures.
256 Each
257 <span class="type">struct addrinfo</span>
258 in this list cn be processed by following
259 the
260 <code class="constant">ai_next</code>
261 pointer, until a
262 <span class="type">NULL</span>
263 pointer is encountered.
264 The three members
265 <code class="constant">ai_family</code>,
266 <code class="constant">ai_socktype</code>,
267 and
268 <code class="constant">ai_protocol</code>
269 in each
270 returned
271 <span class="type">addrinfo</span>
272 structure contain the corresponding arguments for a call to
273 <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>.
274 For each
275 <span class="type">addrinfo</span>
276 structure in the list, the
277 <code class="constant">ai_addr</code>
278 member points to a filled-in socket address structure of length
279 <code class="constant">ai_addrlen</code>.
280 </p>
281 <p>
282 All of the information returned by
283 <code class="function">lwres_getaddrinfo()</code>
284 is dynamically allocated: the addrinfo structures, and the socket
285 address structures and canonical host name strings pointed to by the
286 <code class="constant">addrinfo</code>structures.
287 Memory allocated for the dynamically allocated structures created by
288 a successful call to
289 <code class="function">lwres_getaddrinfo()</code>
290 is released by
291 <code class="function">lwres_freeaddrinfo()</code>.
292 <em class="parameter"><code>ai</code></em>
293 is a pointer to a
294 <span class="type">struct addrinfo</span>
295 created by a call to
296 <code class="function">lwres_getaddrinfo()</code>.
297 </p>
298 </div>
299 <div class="refsect1" lang="en">
300 <a name="id2549874"></a><h2>RETURN VALUES</h2>
301 <p>
302 <code class="function">lwres_getaddrinfo()</code>
303 returns zero on success or one of the error codes listed in
304 <span class="citerefentry"><span class="refentrytitle">gai_strerror</span>(3
305 )</span>
306 if an error occurs.
307 If both
308 <em class="parameter"><code>hostname</code></em>
309 and
310 <em class="parameter"><code>servname</code></em>
311 are
312 <span class="type">NULL</span>
313 <code class="function">lwres_getaddrinfo()</code>
314 returns
315 <span class="errorcode">EAI_NONAME</span>.
316
317 </p>
318 </div>
319 <div class="refsect1" lang="en">
320 <a name="id2549912"></a><h2>SEE ALSO</h2>
321 <p>
322 <span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>,
323
324 <span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>,
325
326 <span class="citerefentry"><span class="refentrytitle">lwres_freeaddrinfo</span>(3)</span>,
327
328 <span class="citerefentry"><span class="refentrytitle">lwres_gai_strerror</span>(3)</span>,
329
330 <span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>,
331
332 <span class="citerefentry"><span class="refentrytitle">getservbyname</span>(3)</span>,
333
334 <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>,
335
336 <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>,
337
338 <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>,
339
340 <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>,
341
342 <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>.
343 </p>
344 </div>
345 </div></body>
346 </html>