Import bind 9.5.2 vendor sources.
[dragonfly.git] / contrib / bind-9.5.2 / lib / lwres / man / lwres_gethostent.html
1 <!--
2  - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
3  - Copyright (C) 2001 Internet Software Consortium.
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: lwres_gethostent.html,v 1.24.214.1 2009/07/11 01:43:34 tbox Exp $ -->
18 <html>
19 <head>
20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
21 <title>lwres_gethostent</title>
22 <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
23 </head>
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="id2476275"></a><div class="titlepage"></div>
26 <div class="refnamediv">
27 <h2>Name</h2>
28 <p>lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent, lwres_sethostent, lwres_endhostent, lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r, lwres_sethostent_r, lwres_endhostent_r &#8212; lightweight resolver get network host entry</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"><tr>
35 <td><code class="funcdef">
36 struct hostent *
37 <b class="fsfunc">lwres_gethostbyname</b>(</code></td>
38 <td>const char * </td>
39 <td>
40 <var class="pdparam">name</var><code>)</code>;</td>
41 </tr></table>
42 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
43 <tr>
44 <td><code class="funcdef">
45 struct hostent *
46 <b class="fsfunc">lwres_gethostbyname2</b>(</code></td>
47 <td>const char * </td>
48 <td>
49 <var class="pdparam">name</var>, </td>
50 </tr>
51 <tr>
52 <td> </td>
53 <td>int  </td>
54 <td>
55 <var class="pdparam">af</var><code>)</code>;</td>
56 </tr>
57 </table>
58 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
59 <tr>
60 <td><code class="funcdef">
61 struct hostent *
62 <b class="fsfunc">lwres_gethostbyaddr</b>(</code></td>
63 <td>const char * </td>
64 <td>
65 <var class="pdparam">addr</var>, </td>
66 </tr>
67 <tr>
68 <td> </td>
69 <td>int  </td>
70 <td>
71 <var class="pdparam">len</var>, </td>
72 </tr>
73 <tr>
74 <td> </td>
75 <td>int  </td>
76 <td>
77 <var class="pdparam">type</var><code>)</code>;</td>
78 </tr>
79 </table>
80 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
81 <td><code class="funcdef">
82 struct hostent *
83 <b class="fsfunc">lwres_gethostent</b>(</code></td>
84 <td> </td>
85 <td>
86 <code>)</code>;</td>
87 </tr></table>
88 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
89 <td><code class="funcdef">
90 void
91 <b class="fsfunc">lwres_sethostent</b>(</code></td>
92 <td>int  </td>
93 <td>
94 <var class="pdparam">stayopen</var><code>)</code>;</td>
95 </tr></table>
96 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
97 <td><code class="funcdef">
98 void
99 <b class="fsfunc">lwres_endhostent</b>(</code></td>
100 <td> </td>
101 <td>
102 <code>)</code>;</td>
103 </tr></table>
104 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
105 <tr>
106 <td><code class="funcdef">
107 struct hostent *
108 <b class="fsfunc">lwres_gethostbyname_r</b>(</code></td>
109 <td>const char * </td>
110 <td>
111 <var class="pdparam">name</var>, </td>
112 </tr>
113 <tr>
114 <td> </td>
115 <td>struct hostent * </td>
116 <td>
117 <var class="pdparam">resbuf</var>, </td>
118 </tr>
119 <tr>
120 <td> </td>
121 <td>char * </td>
122 <td>
123 <var class="pdparam">buf</var>, </td>
124 </tr>
125 <tr>
126 <td> </td>
127 <td>int  </td>
128 <td>
129 <var class="pdparam">buflen</var>, </td>
130 </tr>
131 <tr>
132 <td> </td>
133 <td>int * </td>
134 <td>
135 <var class="pdparam">error</var><code>)</code>;</td>
136 </tr>
137 </table>
138 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
139 <tr>
140 <td><code class="funcdef">
141 struct hostent  *
142 <b class="fsfunc">lwres_gethostbyaddr_r</b>(</code></td>
143 <td>const char * </td>
144 <td>
145 <var class="pdparam">addr</var>, </td>
146 </tr>
147 <tr>
148 <td> </td>
149 <td>int  </td>
150 <td>
151 <var class="pdparam">len</var>, </td>
152 </tr>
153 <tr>
154 <td> </td>
155 <td>int  </td>
156 <td>
157 <var class="pdparam">type</var>, </td>
158 </tr>
159 <tr>
160 <td> </td>
161 <td>struct hostent * </td>
162 <td>
163 <var class="pdparam">resbuf</var>, </td>
164 </tr>
165 <tr>
166 <td> </td>
167 <td>char * </td>
168 <td>
169 <var class="pdparam">buf</var>, </td>
170 </tr>
171 <tr>
172 <td> </td>
173 <td>int  </td>
174 <td>
175 <var class="pdparam">buflen</var>, </td>
176 </tr>
177 <tr>
178 <td> </td>
179 <td>int * </td>
180 <td>
181 <var class="pdparam">error</var><code>)</code>;</td>
182 </tr>
183 </table>
184 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
185 <tr>
186 <td><code class="funcdef">
187 struct hostent  *
188 <b class="fsfunc">lwres_gethostent_r</b>(</code></td>
189 <td>struct hostent * </td>
190 <td>
191 <var class="pdparam">resbuf</var>, </td>
192 </tr>
193 <tr>
194 <td> </td>
195 <td>char * </td>
196 <td>
197 <var class="pdparam">buf</var>, </td>
198 </tr>
199 <tr>
200 <td> </td>
201 <td>int  </td>
202 <td>
203 <var class="pdparam">buflen</var>, </td>
204 </tr>
205 <tr>
206 <td> </td>
207 <td>int * </td>
208 <td>
209 <var class="pdparam">error</var><code>)</code>;</td>
210 </tr>
211 </table>
212 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
213 <td><code class="funcdef">
214 void
215 <b class="fsfunc">lwres_sethostent_r</b>(</code></td>
216 <td>int  </td>
217 <td>
218 <var class="pdparam">stayopen</var><code>)</code>;</td>
219 </tr></table>
220 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr>
221 <td><code class="funcdef">
222 void
223 <b class="fsfunc">lwres_endhostent_r</b>(</code></td>
224 <td> </td>
225 <td>
226 <code>)</code>;</td>
227 </tr></table>
228 </div>
229 </div>
230 <div class="refsect1" lang="en">
231 <a name="id2543608"></a><h2>DESCRIPTION</h2>
232 <p>
233       These functions provide hostname-to-address and
234       address-to-hostname lookups by means of the lightweight resolver.
235       They are similar to the standard
236       <span class="citerefentry"><span class="refentrytitle">gethostent</span>(3)</span>
237       functions provided by most operating systems.
238       They use a
239       <span class="type">struct hostent</span>
240       which is usually defined in
241       <code class="filename">&lt;namedb.h&gt;</code>.
242     </p>
243 <pre class="programlisting">
244 struct  hostent {
245         char    *h_name;        /* official name of host */
246         char    **h_aliases;    /* alias list */
247         int     h_addrtype;     /* host address type */
248         int     h_length;       /* length of address */
249         char    **h_addr_list;  /* list of addresses from name server */
250 };
251 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
252 </pre>
253 <p>
254     </p>
255 <p>
256       The members of this structure are:
257       </p>
258 <div class="variablelist"><dl>
259 <dt><span class="term"><code class="constant">h_name</code></span></dt>
260 <dd><p>
261               The official (canonical) name of the host.
262             </p></dd>
263 <dt><span class="term"><code class="constant">h_aliases</code></span></dt>
264 <dd><p>
265               A NULL-terminated array of alternate names (nicknames) for the
266               host.
267             </p></dd>
268 <dt><span class="term"><code class="constant">h_addrtype</code></span></dt>
269 <dd><p>
270               The type of address being returned &#8212;
271               <span class="type">PF_INET</span>
272               or
273               <span class="type">PF_INET6</span>.
274             </p></dd>
275 <dt><span class="term"><code class="constant">h_length</code></span></dt>
276 <dd><p>
277               The length of the address in bytes.
278             </p></dd>
279 <dt><span class="term"><code class="constant">h_addr_list</code></span></dt>
280 <dd><p>
281               A <span class="type">NULL</span>
282               terminated array of network addresses for the host.
283               Host addresses are returned in network byte order.
284             </p></dd>
285 </dl></div>
286 <p>
287     </p>
288 <p>
289       For backward compatibility with very old software,
290       <code class="constant">h_addr</code>
291       is the first address in
292       <code class="constant">h_addr_list.</code>
293     </p>
294 <p><code class="function">lwres_gethostent()</code>,
295       <code class="function">lwres_sethostent()</code>,
296       <code class="function">lwres_endhostent()</code>,
297       <code class="function">lwres_gethostent_r()</code>,
298       <code class="function">lwres_sethostent_r()</code>
299       and
300       <code class="function">lwres_endhostent_r()</code>
301       provide iteration over the known host entries on systems that
302       provide such functionality through facilities like
303       <code class="filename">/etc/hosts</code>
304       or NIS.  The lightweight resolver does not currently implement
305       these functions; it only provides them as stub functions that always
306       return failure.
307     </p>
308 <p><code class="function">lwres_gethostbyname()</code>
309       and <code class="function">lwres_gethostbyname2()</code> look up the
310       hostname <em class="parameter"><code>name</code></em>.
311       <code class="function">lwres_gethostbyname()</code> always looks for an
312       IPv4 address while <code class="function">lwres_gethostbyname2()</code>
313       looks for an address of protocol family
314       <em class="parameter"><code>af</code></em>: either <span class="type">PF_INET</span> or
315       <span class="type">PF_INET6</span> &#8212; IPv4 or IPV6 addresses
316       respectively.  Successful calls of the functions return a
317       <span class="type">struct hostent</span>for the name that was looked up.
318       <span class="type">NULL</span> is returned if the lookups by
319       <code class="function">lwres_gethostbyname()</code> or
320       <code class="function">lwres_gethostbyname2()</code> fail.
321     </p>
322 <p>
323       Reverse lookups of addresses are performed by
324       <code class="function">lwres_gethostbyaddr()</code>.
325       <em class="parameter"><code>addr</code></em> is an address of length
326       <em class="parameter"><code>len</code></em> bytes and protocol family
327       <em class="parameter"><code>type</code></em> &#8212; <span class="type">PF_INET</span> or
328       <span class="type">PF_INET6</span>.
329       <code class="function">lwres_gethostbyname_r()</code> is a
330       thread-safe function
331       for forward lookups.  If an error occurs, an error code is returned in
332       <em class="parameter"><code>*error</code></em>.
333       <em class="parameter"><code>resbuf</code></em> is a pointer to a
334       <span class="type">struct hostent</span> which is initialised by a successful call to
335       <code class="function">lwres_gethostbyname_r()</code>.
336       <em class="parameter"><code>buf</code></em> is a buffer of length
337       <em class="parameter"><code>len</code></em> bytes which is used to store the
338       <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and
339       <code class="constant">h_addr_list</code> elements of the
340       <span class="type">struct hostent</span> returned in <em class="parameter"><code>resbuf</code></em>.
341       Successful calls to <code class="function">lwres_gethostbyname_r()</code>
342       return <em class="parameter"><code>resbuf</code></em>,
343       which is a pointer to the <span class="type">struct hostent</span> it created.
344     </p>
345 <p><code class="function">lwres_gethostbyaddr_r()</code>
346       is a thread-safe function
347       that performs a reverse lookup of address <em class="parameter"><code>addr</code></em>
348       which is <em class="parameter"><code>len</code></em> bytes long and is of
349       protocol
350       family <em class="parameter"><code>type</code></em> &#8212; <span class="type">PF_INET</span> or
351       <span class="type">PF_INET6</span>.  If an error occurs, the error code is returned
352       in <em class="parameter"><code>*error</code></em>.  The other function
353       parameters are
354       identical to those in <code class="function">lwres_gethostbyname_r()</code>.
355       <em class="parameter"><code>resbuf</code></em> is a pointer to a
356       <span class="type">struct hostent</span> which is initialised by a successful call to
357       <code class="function">lwres_gethostbyaddr_r()</code>.
358       <em class="parameter"><code>buf</code></em> is a buffer of length
359       <em class="parameter"><code>len</code></em> bytes which is used to store the
360       <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and
361       <code class="constant">h_addr_list</code> elements of the
362       <span class="type">struct hostent</span> returned in <em class="parameter"><code>resbuf</code></em>.
363       Successful calls to <code class="function">lwres_gethostbyaddr_r()</code> return
364       <em class="parameter"><code>resbuf</code></em>, which is a pointer to the
365       <code class="function">struct hostent()</code> it created.
366     </p>
367 </div>
368 <div class="refsect1" lang="en">
369 <a name="id2543959"></a><h2>RETURN VALUES</h2>
370 <p>
371       The functions
372       <code class="function">lwres_gethostbyname()</code>,
373       <code class="function">lwres_gethostbyname2()</code>,
374       <code class="function">lwres_gethostbyaddr()</code>,
375       and
376       <code class="function">lwres_gethostent()</code>
377       return NULL to indicate an error.  In this case the global variable
378       <span class="type">lwres_h_errno</span>
379       will contain one of the following error codes defined in
380       <code class="filename">&lt;lwres/netdb.h&gt;</code>:
381
382       </p>
383 <div class="variablelist"><dl>
384 <dt><span class="term"><code class="constant">HOST_NOT_FOUND</code></span></dt>
385 <dd><p>
386               The host or address was not found.
387             </p></dd>
388 <dt><span class="term"><code class="constant">TRY_AGAIN</code></span></dt>
389 <dd><p>
390               A recoverable error occurred, e.g., a timeout.
391               Retrying the lookup may succeed.
392             </p></dd>
393 <dt><span class="term"><code class="constant">NO_RECOVERY</code></span></dt>
394 <dd><p>
395               A non-recoverable error occurred.
396             </p></dd>
397 <dt><span class="term"><code class="constant">NO_DATA</code></span></dt>
398 <dd><p>
399               The name exists, but has no address information
400               associated with it (or vice versa in the case
401               of a reverse lookup).  The code NO_ADDRESS
402               is accepted as a synonym for NO_DATA for backwards
403               compatibility.
404             </p></dd>
405 </dl></div>
406 <p>
407     </p>
408 <p><span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>
409       translates these error codes to suitable error messages.
410     </p>
411 <p><code class="function">lwres_gethostent()</code>
412       and <code class="function">lwres_gethostent_r()</code>
413       always return <span class="type">NULL</span>.
414     </p>
415 <p>
416       Successful calls to <code class="function">lwres_gethostbyname_r()</code> and
417       <code class="function">lwres_gethostbyaddr_r()</code> return
418       <em class="parameter"><code>resbuf</code></em>, a pointer to the
419       <span class="type">struct hostent</span> that was initialised by these functions.  They return
420       <span class="type">NULL</span> if the lookups fail or if <em class="parameter"><code>buf</code></em>
421       was too small to hold the list of addresses and names referenced by
422       the <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and
423       <code class="constant">h_addr_list</code> elements of the
424       <span class="type">struct hostent</span>.
425       If <em class="parameter"><code>buf</code></em> was too small, both
426       <code class="function">lwres_gethostbyname_r()</code> and
427       <code class="function">lwres_gethostbyaddr_r()</code> set the global
428       variable
429       <span class="type">errno</span> to <span class="errorcode">ERANGE</span>.
430     </p>
431 </div>
432 <div class="refsect1" lang="en">
433 <a name="id2544193"></a><h2>SEE ALSO</h2>
434 <p><span class="citerefentry"><span class="refentrytitle">gethostent</span>(3)</span>,
435
436       <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>,
437
438       <span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>
439     </p>
440 </div>
441 <div class="refsect1" lang="en">
442 <a name="id2544227"></a><h2>BUGS</h2>
443 <p><code class="function">lwres_gethostbyname()</code>,
444       <code class="function">lwres_gethostbyname2()</code>,
445       <code class="function">lwres_gethostbyaddr()</code>
446       and
447       <code class="function">lwres_endhostent()</code>
448       are not thread safe; they return pointers to static data and
449       provide error codes through a global variable.
450       Thread-safe versions for name and address lookup are provided by
451       <code class="function">lwres_gethostbyname_r()</code>,
452       and
453       <code class="function">lwres_gethostbyaddr_r()</code>
454       respectively.
455     </p>
456 <p>
457       The resolver daemon does not currently support any non-DNS
458       name services such as
459       <code class="filename">/etc/hosts</code>
460       or
461       <span class="type">NIS</span>,
462       consequently the above functions don't, either.
463     </p>
464 </div>
465 </div></body>
466 </html>