<!-- - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and 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 INTERNET SOFTWARE CONSORTIUM - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL - INTERNET SOFTWARE CONSORTIUM 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. --> <HTML ><HEAD ><TITLE >lwres_gethostent</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.73 "></HEAD ><BODY CLASS="REFENTRY" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><H1 ><A NAME="AEN1" >lwres_gethostent</A ></H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN8" ></A ><H2 >Name</H2 >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 -- lightweight resolver get network host entry</DIV ><DIV CLASS="REFSYNOPSISDIV" ><A NAME="AEN21" ></A ><H2 >Synopsis</H2 ><DIV CLASS="FUNCSYNOPSIS" ><A NAME="AEN22" ></A ><P ></P ><PRE CLASS="FUNCSYNOPSISINFO" >#include <lwres/netdb.h></PRE ><P ><CODE ><CODE CLASS="FUNCDEF" >struct hostent * lwres_gethostbyname</CODE >(const char *name);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >struct hostent * lwres_gethostbyname2</CODE >(const char *name, int af);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >struct hostent * lwres_gethostbyaddr</CODE >(const char *addr, int len, int type);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >struct hostent * lwres_gethostent</CODE >(void);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >void lwres_sethostent</CODE >(int stayopen);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >void lwres_endhostent</CODE >(void);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >struct hostent * lwres_gethostbyname_r</CODE >(const char *name, struct hostent *resbuf, char *buf, int buflen, int *error);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >struct hostent * lwres_gethostbyaddr_r</CODE >(const char *addr, int len, int type, struct hostent *resbuf, char *buf, int buflen, int *error);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >struct hostent * lwres_gethostent_r</CODE >(struct hostent *resbuf, char *buf, int buflen, int *error);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >void lwres_sethostent_r</CODE >(int stayopen);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >void lwres_endhostent_r</CODE >(void);</CODE ></P ><P ></P ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN84" ></A ><H2 >DESCRIPTION</H2 ><P >These functions provide hostname-to-address and address-to-hostname lookups by means of the lightweight resolver. They are similar to the standard <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >gethostent</SPAN >(3)</SPAN > functions provided by most operating systems. They use a <SPAN CLASS="TYPE" >struct hostent</SPAN > which is usually defined in <TT CLASS="FILENAME" ><namedb.h></TT >. <PRE CLASS="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 */</PRE ></P ><P >The members of this structure are: <P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="CONSTANT" >h_name</TT ></DT ><DD ><P >The official (canonical) name of the host.</P ></DD ><DT ><TT CLASS="CONSTANT" >h_aliases</TT ></DT ><DD ><P >A NULL-terminated array of alternate names (nicknames) for the host.</P ></DD ><DT ><TT CLASS="CONSTANT" >h_addrtype</TT ></DT ><DD ><P >The type of address being returned — <SPAN CLASS="TYPE" >PF_INET</SPAN > or <SPAN CLASS="TYPE" >PF_INET6</SPAN >.</P ></DD ><DT ><TT CLASS="CONSTANT" >h_length</TT ></DT ><DD ><P >The length of the address in bytes.</P ></DD ><DT ><TT CLASS="CONSTANT" >h_addr_list</TT ></DT ><DD ><P >A <SPAN CLASS="TYPE" >NULL</SPAN > terminated array of network addresses for the host. Host addresses are returned in network byte order.</P ></DD ></DL ></DIV ></P ><P >For backward compatibility with very old software, <TT CLASS="CONSTANT" >h_addr</TT > is the first address in <TT CLASS="CONSTANT" >h_addr_list.</TT ></P ><P ><TT CLASS="FUNCTION" >lwres_gethostent()</TT >, <TT CLASS="FUNCTION" >lwres_sethostent()</TT >, <TT CLASS="FUNCTION" >lwres_endhostent()</TT >, <TT CLASS="FUNCTION" >lwres_gethostent_r()</TT >, <TT CLASS="FUNCTION" >lwres_sethostent_r()</TT > and <TT CLASS="FUNCTION" >lwres_endhostent_r()</TT > provide iteration over the known host entries on systems that provide such functionality through facilities like <TT CLASS="FILENAME" >/etc/hosts</TT > or NIS. The lightweight resolver does not currently implement these functions; it only provides them as stub functions that always return failure.</P ><P ><TT CLASS="FUNCTION" >lwres_gethostbyname()</TT > and <TT CLASS="FUNCTION" >lwres_gethostbyname2()</TT > look up the hostname <TT CLASS="PARAMETER" ><I >name</I ></TT >. <TT CLASS="FUNCTION" >lwres_gethostbyname()</TT > always looks for an IPv4 address while <TT CLASS="FUNCTION" >lwres_gethostbyname2()</TT > looks for an address of protocol family <TT CLASS="PARAMETER" ><I >af</I ></TT >: either <SPAN CLASS="TYPE" >PF_INET</SPAN > or <SPAN CLASS="TYPE" >PF_INET6</SPAN > — IPv4 or IPV6 addresses respectively. Successful calls of the functions return a <SPAN CLASS="TYPE" >struct hostent</SPAN >for the name that was looked up. <SPAN CLASS="TYPE" >NULL</SPAN > is returned if the lookups by <TT CLASS="FUNCTION" >lwres_gethostbyname()</TT > or <TT CLASS="FUNCTION" >lwres_gethostbyname2()</TT > fail.</P ><P >Reverse lookups of addresses are performed by <TT CLASS="FUNCTION" >lwres_gethostbyaddr()</TT >. <TT CLASS="PARAMETER" ><I >addr</I ></TT > is an address of length <TT CLASS="PARAMETER" ><I >len</I ></TT > bytes and protocol family <TT CLASS="PARAMETER" ><I >type</I ></TT > — <SPAN CLASS="TYPE" >PF_INET</SPAN > or <SPAN CLASS="TYPE" >PF_INET6</SPAN >. <TT CLASS="FUNCTION" >lwres_gethostbyname_r()</TT > is a thread-safe function for forward lookups. If an error occurs, an error code is returned in <TT CLASS="PARAMETER" ><I >*error</I ></TT >. <TT CLASS="PARAMETER" ><I >resbuf</I ></TT > is a pointer to a <SPAN CLASS="TYPE" >struct hostent</SPAN > which is initialised by a successful call to <TT CLASS="FUNCTION" >lwres_gethostbyname_r()</TT > . <TT CLASS="PARAMETER" ><I >buf</I ></TT > is a buffer of length <TT CLASS="PARAMETER" ><I >len</I ></TT > bytes which is used to store the <TT CLASS="CONSTANT" >h_name</TT >, <TT CLASS="CONSTANT" >h_aliases</TT >, and <TT CLASS="CONSTANT" >h_addr_list</TT > elements of the <SPAN CLASS="TYPE" >struct hostent</SPAN > returned in <TT CLASS="PARAMETER" ><I >resbuf</I ></TT >. Successful calls to <TT CLASS="FUNCTION" >lwres_gethostbyname_r()</TT > return <TT CLASS="PARAMETER" ><I >resbuf</I ></TT >, which is a pointer to the <SPAN CLASS="TYPE" >struct hostent</SPAN > it created.</P ><P ><TT CLASS="FUNCTION" >lwres_gethostbyaddr_r()</TT > is a thread-safe function that performs a reverse lookup of address <TT CLASS="PARAMETER" ><I >addr</I ></TT > which is <TT CLASS="PARAMETER" ><I >len</I ></TT > bytes long and is of protocol family <TT CLASS="PARAMETER" ><I >type</I ></TT > — <SPAN CLASS="TYPE" >PF_INET</SPAN > or <SPAN CLASS="TYPE" >PF_INET6</SPAN >. If an error occurs, the error code is returned in <TT CLASS="PARAMETER" ><I >*error</I ></TT >. The other function parameters are identical to those in <TT CLASS="FUNCTION" >lwres_gethostbyname_r()</TT >. <TT CLASS="PARAMETER" ><I >resbuf</I ></TT > is a pointer to a <SPAN CLASS="TYPE" >struct hostent</SPAN > which is initialised by a successful call to <TT CLASS="FUNCTION" >lwres_gethostbyaddr_r()</TT >. <TT CLASS="PARAMETER" ><I >buf</I ></TT > is a buffer of length <TT CLASS="PARAMETER" ><I >len</I ></TT > bytes which is used to store the <TT CLASS="CONSTANT" >h_name</TT >, <TT CLASS="CONSTANT" >h_aliases</TT >, and <TT CLASS="CONSTANT" >h_addr_list</TT > elements of the <SPAN CLASS="TYPE" >struct hostent</SPAN > returned in <TT CLASS="PARAMETER" ><I >resbuf</I ></TT >. Successful calls to <TT CLASS="FUNCTION" >lwres_gethostbyaddr_r()</TT > return <TT CLASS="PARAMETER" ><I >resbuf</I ></TT >, which is a pointer to the <TT CLASS="FUNCTION" >struct hostent()</TT > it created.</P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN191" ></A ><H2 >RETURN VALUES</H2 ><P >The functions <TT CLASS="FUNCTION" >lwres_gethostbyname()</TT >, <TT CLASS="FUNCTION" >lwres_gethostbyname2()</TT >, <TT CLASS="FUNCTION" >lwres_gethostbyaddr()</TT >, and <TT CLASS="FUNCTION" >lwres_gethostent()</TT > return NULL to indicate an error. In this case the global variable <SPAN CLASS="TYPE" >lwres_h_errno</SPAN > will contain one of the following error codes defined in <TT CLASS="FILENAME" ><lwres/netdb.h></TT >: <P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="CONSTANT" >HOST_NOT_FOUND</TT ></DT ><DD ><P >The host or address was not found.</P ></DD ><DT ><TT CLASS="CONSTANT" >TRY_AGAIN</TT ></DT ><DD ><P >A recoverable error occurred, e.g., a timeout. Retrying the lookup may succeed.</P ></DD ><DT ><TT CLASS="CONSTANT" >NO_RECOVERY</TT ></DT ><DD ><P >A non-recoverable error occurred.</P ></DD ><DT ><TT CLASS="CONSTANT" >NO_DATA</TT ></DT ><DD ><P >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.</P ></DD ></DL ></DIV ></P ><P ><SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >lwres_hstrerror</SPAN >(3)</SPAN > translates these error codes to suitable error messages.</P ><P ><TT CLASS="FUNCTION" >lwres_gethostent()</TT > and <TT CLASS="FUNCTION" >lwres_gethostent_r()</TT > always return <SPAN CLASS="TYPE" >NULL</SPAN >.</P ><P >Successful calls to <TT CLASS="FUNCTION" >lwres_gethostbyname_r()</TT > and <TT CLASS="FUNCTION" >lwres_gethostbyaddr_r()</TT > return <TT CLASS="PARAMETER" ><I >resbuf</I ></TT >, a pointer to the <SPAN CLASS="TYPE" >struct hostent</SPAN > that was initialised by these functions. They return <SPAN CLASS="TYPE" >NULL</SPAN > if the lookups fail or if <TT CLASS="PARAMETER" ><I >buf</I ></TT > was too small to hold the list of addresses and names referenced by the <TT CLASS="CONSTANT" >h_name</TT >, <TT CLASS="CONSTANT" >h_aliases</TT >, and <TT CLASS="CONSTANT" >h_addr_list</TT > elements of the <SPAN CLASS="TYPE" >struct hostent</SPAN >. If <TT CLASS="PARAMETER" ><I >buf</I ></TT > was too small, both <TT CLASS="FUNCTION" >lwres_gethostbyname_r()</TT > and <TT CLASS="FUNCTION" >lwres_gethostbyaddr_r()</TT > set the global variable <SPAN CLASS="TYPE" >errno</SPAN > to <SPAN CLASS="ERRORCODE" >ERANGE</SPAN >.</P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN245" ></A ><H2 >SEE ALSO</H2 ><P ><SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >gethostent</SPAN >(3)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >lwres_getipnode</SPAN >(3)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >lwres_hstrerror</SPAN >(3)</SPAN ></P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN257" ></A ><H2 >BUGS</H2 ><P ><TT CLASS="FUNCTION" >lwres_gethostbyname()</TT >, <TT CLASS="FUNCTION" >lwres_gethostbyname2()</TT >, <TT CLASS="FUNCTION" >lwres_gethostbyaddr()</TT > and <TT CLASS="FUNCTION" >lwres_endhostent()</TT > 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 <TT CLASS="FUNCTION" >lwres_gethostbyname_r()</TT >, and <TT CLASS="FUNCTION" >lwres_gethostbyaddr_r()</TT > respectively.</P ><P >The resolver daemon does not currently support any non-DNS name services such as <TT CLASS="FILENAME" >/etc/hosts</TT > or <SPAN CLASS="TYPE" >NIS</SPAN >, consequently the above functions don't, either.</P ></DIV ></BODY ></HTML >