lwres_gethostent.docbook

非常好的dns解析软件

            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>
    <para>
      For backward compatibility with very old software,
      <constant>h_addr</constant>
      is the first address in
      <constant>h_addr_list.</constant>
    </para>
    <para><function>lwres_gethostent()</function>,
      <function>lwres_sethostent()</function>,
      <function>lwres_endhostent()</function>,
      <function>lwres_gethostent_r()</function>,
      <function>lwres_sethostent_r()</function>
      and
      <function>lwres_endhostent_r()</function>
      provide iteration over the known host entries on systems that
      provide such functionality through facilities like
      <filename>/etc/hosts</filename>
      or NIS.  The lightweight resolver does not currently implement
      these functions; it only provides them as stub functions that always
      return failure.
    </para>

    <para><function>lwres_gethostbyname()</function>
      and <function>lwres_gethostbyname2()</function> look up the
      hostname <parameter>name</parameter>.
      <function>lwres_gethostbyname()</function> always looks for an
      IPv4 address while <function>lwres_gethostbyname2()</function>
      looks for an address of protocol family
      <parameter>af</parameter>: either <type>PF_INET</type> or
      <type>PF_INET6</type> &mdash; IPv4 or IPV6 addresses
      respectively.  Successful calls of the functions return a
      <type>struct hostent</type>for the name that was looked up.
      <type>NULL</type> is returned if the lookups by
      <function>lwres_gethostbyname()</function> or
      <function>lwres_gethostbyname2()</function> fail.
    </para>

    <para>
      Reverse lookups of addresses are performed by
      <function>lwres_gethostbyaddr()</function>.
      <parameter>addr</parameter> is an address of length
      <parameter>len</parameter> bytes and protocol family
      <parameter>type</parameter> &mdash; <type>PF_INET</type> or
      <type>PF_INET6</type>.
      <function>lwres_gethostbyname_r()</function> is a
      thread-safe function
      for forward lookups.  If an error occurs, an error code is returned in
      <parameter>*error</parameter>.
      <parameter>resbuf</parameter> is a pointer to a
      <type>struct hostent</type> which is initialised by a successful call to
      <function>lwres_gethostbyname_r()</function>.
      <parameter>buf</parameter> is a buffer of length
      <parameter>len</parameter> bytes which is used to store the
      <constant>h_name</constant>, <constant>h_aliases</constant>, and
      <constant>h_addr_list</constant> elements of the
      <type>struct hostent</type> returned in <parameter>resbuf</parameter>.
      Successful calls to <function>lwres_gethostbyname_r()</function>
      return <parameter>resbuf</parameter>,
      which is a pointer to the <type>struct hostent</type> it created.
    </para>

    <para><function>lwres_gethostbyaddr_r()</function>
      is a thread-safe function
      that performs a reverse lookup of address <parameter>addr</parameter>
      which is <parameter>len</parameter> bytes long and is of
      protocol
      family <parameter>type</parameter> &mdash; <type>PF_INET</type> or
      <type>PF_INET6</type>.  If an error occurs, the error code is returned
      in <parameter>*error</parameter>.  The other function
      parameters are
      identical to those in <function>lwres_gethostbyname_r()</function>.
      <parameter>resbuf</parameter> is a pointer to a
      <type>struct hostent</type> which is initialised by a successful call to
      <function>lwres_gethostbyaddr_r()</function>.
      <parameter>buf</parameter> is a buffer of length
      <parameter>len</parameter> bytes which is used to store the
      <constant>h_name</constant>, <constant>h_aliases</constant>, and
      <constant>h_addr_list</constant> elements of the
      <type>struct hostent</type> returned in <parameter>resbuf</parameter>.
      Successful calls to <function>lwres_gethostbyaddr_r()</function> return
      <parameter>resbuf</parameter>, which is a pointer to the
      <function>struct hostent()</function> it created.
    </para>

  </refsect1>

  <refsect1>
    <title>RETURN VALUES</title>
    <para>
      The functions
      <function>lwres_gethostbyname()</function>,
      <function>lwres_gethostbyname2()</function>,
      <function>lwres_gethostbyaddr()</function>,
      and
      <function>lwres_gethostent()</function>
      return NULL to indicate an error.  In this case the global variable
      <type>lwres_h_errno</type>
      will contain one of the following error codes defined in
      <filename>&lt;lwres/netdb.h&gt;</filename>:

      <variablelist>
        <varlistentry>
          <term><constant>HOST_NOT_FOUND</constant></term>
          <listitem>
            <para>
              The host or address was not found.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><constant>TRY_AGAIN</constant></term>
          <listitem>
            <para>
              A recoverable error occurred, e.g., a timeout.
              Retrying the lookup may succeed.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><constant>NO_RECOVERY</constant></term>
          <listitem>
            <para>
              A non-recoverable error occurred.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><constant>NO_DATA</constant></term>
          <listitem>
            <para>
              The name exists, but has no address information
              associated with it (or vice versa in the case
              of a reverse lookup).  The code NO_ADDRESS
              is accepted as a synonym for NO_DATA for backwards
              compatibility.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>

    <para><citerefentry>
        <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>
      translates these error codes to suitable error messages.
    </para>

    <para><function>lwres_gethostent()</function>
      and <function>lwres_gethostent_r()</function>
      always return <type>NULL</type>.
    </para>

    <para>
      Successful calls to <function>lwres_gethostbyname_r()</function> and
      <function>lwres_gethostbyaddr_r()</function> return
      <parameter>resbuf</parameter>, a pointer to the
      <type>struct hostent</type> that was initialised by these functions.  They return
      <type>NULL</type> if the lookups fail or if <parameter>buf</parameter>
      was too small to hold the list of addresses and names referenced by
      the <constant>h_name</constant>, <constant>h_aliases</constant>, and
      <constant>h_addr_list</constant> elements of the
      <type>struct hostent</type>.
      If <parameter>buf</parameter> was too small, both
      <function>lwres_gethostbyname_r()</function> and
      <function>lwres_gethostbyaddr_r()</function> set the global
      variable
      <type>errno</type> to <errorcode>ERANGE</errorcode>.
    </para>

  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>
    <para><citerefentry>
        <refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>
    </para>
  </refsect1>

  <refsect1>
    <title>BUGS</title>
    <para><function>lwres_gethostbyname()</function>,
      <function>lwres_gethostbyname2()</function>,
      <function>lwres_gethostbyaddr()</function>
      and
      <function>lwres_endhostent()</function>
      are not thread safe; they return pointers to static data and
      provide error codes through a global variable.
      Thread-safe versions for name and address lookup are provided by
      <function>lwres_gethostbyname_r()</function>,
      and
      <function>lwres_gethostbyaddr_r()</function>
      respectively.
    </para>
    <para>
      The resolver daemon does not currently support any non-DNS
      name services such as
      <filename>/etc/hosts</filename>
      or
      <type>NIS</type>,
      consequently the above functions don't, either.
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->