PageRenderTime 22ms CodeModel.GetById 10ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/bind9/lib/lwres/man/lwres_gethostent.docbook

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