diff options
Diffstat (limited to 'lib/lwres/man/lwres_gethostent.docbook')
| -rw-r--r-- | lib/lwres/man/lwres_gethostent.docbook | 439 |
1 files changed, 439 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_gethostent.docbook b/lib/lwres/man/lwres_gethostent.docbook new file mode 100644 index 0000000..a3f084b --- /dev/null +++ b/lib/lwres/man/lwres_gethostent.docbook @@ -0,0 +1,439 @@ +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" + [<!ENTITY mdash "—">]> +<!-- + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2001 Internet Software Consortium. + - + - Permission to use, copy, modify, and/or distribute this software for any + - purpose with or without fee is hereby granted, provided that the above + - copyright notice and this permission notice appear in all copies. + - + - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH + - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, + - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE + - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + - PERFORMANCE OF THIS SOFTWARE. +--> + +<!-- $Id: lwres_gethostent.docbook,v 1.11 2007/06/18 23:47:51 tbox Exp $ --> +<refentry> + + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> + + <refmeta> + <refentrytitle>lwres_gethostent</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> + + <docinfo> + <copyright> + <year>2004</year> + <year>2005</year> + <year>2007</year> + <holder>Internet Systems Consortium, Inc. ("ISC")</holder> + </copyright> + <copyright> + <year>2001</year> + <holder>Internet Software Consortium.</holder> + </copyright> + </docinfo> + + <refnamediv> + <refname>lwres_gethostbyname</refname> + <refname>lwres_gethostbyname2</refname> + <refname>lwres_gethostbyaddr</refname> + <refname>lwres_gethostent</refname> + <refname>lwres_sethostent</refname> + <refname>lwres_endhostent</refname> + <refname>lwres_gethostbyname_r</refname> + <refname>lwres_gethostbyaddr_r</refname> + <refname>lwres_gethostent_r</refname> + <refname>lwres_sethostent_r</refname> + <refname>lwres_endhostent_r</refname> + <refpurpose>lightweight resolver get network host entry</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> +<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> +<funcprototype> + <funcdef> +struct hostent * +<function>lwres_gethostbyname</function></funcdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + </funcprototype> +<funcprototype> + <funcdef> +struct hostent * +<function>lwres_gethostbyname2</function></funcdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>int <parameter>af</parameter></paramdef> + </funcprototype> +<funcprototype> + <funcdef> +struct hostent * +<function>lwres_gethostbyaddr</function></funcdef> + <paramdef>const char *<parameter>addr</parameter></paramdef> + <paramdef>int <parameter>len</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + </funcprototype> +<funcprototype> + <funcdef> +struct hostent * +<function>lwres_gethostent</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> +<funcprototype> + <funcdef> +void +<function>lwres_sethostent</function></funcdef> + <paramdef>int <parameter>stayopen</parameter></paramdef> + </funcprototype> +<funcprototype> + <funcdef> +void +<function>lwres_endhostent</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> +<funcprototype> + <funcdef> +struct hostent * +<function>lwres_gethostbyname_r</function></funcdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef> + <paramdef>char *<parameter>buf</parameter></paramdef> + <paramdef>int <parameter>buflen</parameter></paramdef> + <paramdef>int *<parameter>error</parameter></paramdef> + </funcprototype> +<funcprototype> + <funcdef> +struct hostent * +<function>lwres_gethostbyaddr_r</function></funcdef> + <paramdef>const char *<parameter>addr</parameter></paramdef> + <paramdef>int <parameter>len</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef> + <paramdef>char *<parameter>buf</parameter></paramdef> + <paramdef>int <parameter>buflen</parameter></paramdef> + <paramdef>int *<parameter>error</parameter></paramdef> + </funcprototype> +<funcprototype> + <funcdef> +struct hostent * +<function>lwres_gethostent_r</function></funcdef> + <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef> + <paramdef>char *<parameter>buf</parameter></paramdef> + <paramdef>int <parameter>buflen</parameter></paramdef> + <paramdef>int *<parameter>error</parameter></paramdef> + </funcprototype> +<funcprototype> + <funcdef> +void +<function>lwres_sethostent_r</function></funcdef> + <paramdef>int <parameter>stayopen</parameter></paramdef> + </funcprototype> +<funcprototype> + <funcdef> +void +<function>lwres_endhostent_r</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> +</funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>DESCRIPTION</title> + <para> + These functions provide hostname-to-address and + address-to-hostname lookups by means of the lightweight resolver. + They are similar to the standard + <citerefentry> + <refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> + functions provided by most operating systems. + They use a + <type>struct hostent</type> + which is usually defined in + <filename><namedb.h></filename>. + </para> + <para><programlisting> +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses from name server */ +}; +#define h_addr h_addr_list[0] /* address, for backward compatibility */ +</programlisting> + </para> + <para> + The members of this structure are: + <variablelist> + <varlistentry> + <term><constant>h_name</constant></term> + <listitem> + <para> + The official (canonical) name of the host. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_aliases</constant></term> + <listitem> + <para> + A NULL-terminated array of alternate names (nicknames) for the + host. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_addrtype</constant></term> + <listitem> + <para> + The type of address being returned — + <type>PF_INET</type> + or + <type>PF_INET6</type>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_length</constant></term> + <listitem> + <para> + The length of the address in bytes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_addr_list</constant></term> + <listitem> + <para> + A <type>NULL</type> + terminated array of network addresses for the host. + Host addresses are returned in network byte order. + </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> — 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> — <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> — <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><lwres/netdb.h></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: +--> |