lwres_gethostent.docbook revision d4ef65050feac78554addf6e16a06c6e2e0bd331
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - Copyright (C) 2001 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington<!-- $Id: lwres_gethostent.docbook,v 1.2 2001/04/10 21:51:40 bwelling Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refentryinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_gethostent</refentrytitle>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refpurpose>lightweight resolver get network host entry</refpurpose>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname2</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyaddr</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostent</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_sethostent</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_endhostent</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname_r</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>struct hostent *resbuf</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyaddr_r</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>struct hostent *resbuf</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostent_r</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>struct hostent *resbuf</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_sethostent_r</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_endhostent_r</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese functions provide hostname-to-address and
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonaddress-to-hostname lookups by means of the lightweight resolver.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThey are similar to the standard
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>gethostent</refentrytitle><manvolnum>3
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfunctions provided by most operating systems.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhich is usually defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent {
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson char *h_name; /* official name of host */
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson char **h_aliases; /* alias list */
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson int h_addrtype; /* host address type */
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson int h_length; /* length of address */
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson char **h_addr_list; /* list of addresses from name server */
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson#define h_addr h_addr_list[0] /* address, for backward compatibility */
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe members of this structure are:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>h_name</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe official (canonical) name of the host.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>h_aliases</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonA NULL-terminated array of alternate names (nicknames) for the host.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>h_addrtype</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe type of address being returned —
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>h_length</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe length of the address in bytes.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>h_addr_list</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonterminated array of network addresses for the host.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonHost addresses are returned in network byte order.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</variablelist>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonFor backward compatibility with very old software,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis the first address in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostent_r()</function>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonprovide iteration over the known host entries on systems that
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonprovide such functionality through facilities like
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonor NIS. The lightweight resolver does not currently implement
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthese functions; it only provides them as stub functions that always
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonreturn failure.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname2()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlook up the hostname
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonalways looks for an IPv4 address while
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname2()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlooks for an address of protocol family
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson— IPv4 or IPV6 addresses respectively.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonSuccessful calls of the functions return a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthe name that was looked up.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis returned if the lookups by
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname2()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonReverse lookups of addresses are performed by
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyaddr()</function>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis an address of length
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonbytes and protocol family
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname_r()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis a thread-safe function for forward lookups.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIf an error occurs, an error code is returned in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis a pointer to a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhich is initialised by a successful call to
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname_r()</function> .
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis a buffer of length
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonbytes which is used to store the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonelements of the
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonSuccessful calls to
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname_r()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhich is a pointer to the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyaddr_r()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis a thread-safe function that performs a reverse lookup of address
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand is of protocol family
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIf an error occurs, the error code is returned in
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe other function parameters are identical to those in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname_r()</function>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis a pointer to a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhich is initialised by a successful call to
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyaddr_r()</function>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis a buffer of length
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonbytes which is used to store the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonelements of the
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonSuccessful calls to
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyaddr_r()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhich is a pointer to the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname()</function>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname2()</function>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyaddr()</function>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonreturn NULL to indicate an error. In this case the global variable
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwill contain one of the following error codes defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<filename><lwres/netdb.h></filename>:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe host or address was not found.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>TRY_AGAIN</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonA recoverable error occurred, e.g., a timeout.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonRetrying the lookup may succeed.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>NO_RECOVERY</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonA non-recoverable error occurred.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>NO_DATA</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe name exists, but has no address information
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonassociated with it (or vice versa in the case
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonof a reverse lookup). The code NO_ADDRESS
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis accepted as a synonym for NO_DATA for backwards
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</variablelist>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontranslates these error codes to suitable error messages.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonSuccessful calls to
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname_r()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyaddr_r()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssona pointer to the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthat was initialised by these functions.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the lookups fail
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwas too small to hold the list of addresses and names referenced by
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonelements of the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwas too small, both
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname_r()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyaddr_r()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonset the global variable
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname()</function>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname2()</function>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyaddr()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonare not thread safe; they return pointers to static data and
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonprovide error codes through a global variable.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThread-safe versions for name and address lookup are provided by
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyname_r()</function>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gethostbyaddr_r()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe resolver daemon does not currently support any non-DNS
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonname services such as
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonconsequently the above functions don't, either.