<!--
- Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 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 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.html,v 1.8.2.1.4.2 2004/08/22 23:39:04 marka Exp $ -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>lwres_gethostent</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><H1
><A
NAME="AEN1"
></A
>lwres_gethostent</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"
><P
></P
><A
NAME="AEN22"
></A
><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
><CODE
CLASS="CONSTANT"
>h_name</CODE
></DT
><DD
><P
>The official (canonical) name of the host.</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>h_aliases</CODE
></DT
><DD
><P
>A NULL-terminated array of alternate names (nicknames) for the host.</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>h_addrtype</CODE
></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
><CODE
CLASS="CONSTANT"
>h_length</CODE
></DT
><DD
><P
>The length of the address in bytes.</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>h_addr_list</CODE
></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,
<CODE
CLASS="CONSTANT"
>h_addr</CODE
>
is the first address in
<CODE
CLASS="CONSTANT"
>h_addr_list.</CODE
></P
><P
><CODE
CLASS="FUNCTION"
>lwres_gethostent()</CODE
>,
<CODE
CLASS="FUNCTION"
>lwres_sethostent()</CODE
>,
<CODE
CLASS="FUNCTION"
>lwres_endhostent()</CODE
>,
<CODE
CLASS="FUNCTION"
>lwres_gethostent_r()</CODE
>,
<CODE
CLASS="FUNCTION"
>lwres_sethostent_r()</CODE
>
and
<CODE
CLASS="FUNCTION"
>lwres_endhostent_r()</CODE
>
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
><CODE
CLASS="FUNCTION"
>lwres_gethostbyname()</CODE
> and
<CODE
CLASS="FUNCTION"
>lwres_gethostbyname2()</CODE
> look up the hostname
<VAR
CLASS="PARAMETER"
>name</VAR
>.
<CODE
CLASS="FUNCTION"
>lwres_gethostbyname()</CODE
> always looks for an IPv4
address while <CODE
CLASS="FUNCTION"
>lwres_gethostbyname2()</CODE
> looks for an
address of protocol family <VAR
CLASS="PARAMETER"
>af</VAR
>: 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
<CODE
CLASS="FUNCTION"
>lwres_gethostbyname()</CODE
> or
<CODE
CLASS="FUNCTION"
>lwres_gethostbyname2()</CODE
> fail.</P
><P
>Reverse lookups of addresses are performed by
<CODE
CLASS="FUNCTION"
>lwres_gethostbyaddr()</CODE
>.
<VAR
CLASS="PARAMETER"
>addr</VAR
> is an address of length
<VAR
CLASS="PARAMETER"
>len</VAR
> bytes and protocol family
<VAR
CLASS="PARAMETER"
>type</VAR
> — <SPAN
CLASS="TYPE"
>PF_INET</SPAN
> or
<SPAN
CLASS="TYPE"
>PF_INET6</SPAN
>.
<CODE
CLASS="FUNCTION"
>lwres_gethostbyname_r()</CODE
> is a thread-safe function
for forward lookups. If an error occurs, an error code is returned in
<VAR
CLASS="PARAMETER"
>*error</VAR
>.
<VAR
CLASS="PARAMETER"
>resbuf</VAR
> is a pointer to a <SPAN
CLASS="TYPE"
>struct
hostent</SPAN
> which is initialised by a successful call to
<CODE
CLASS="FUNCTION"
>lwres_gethostbyname_r()</CODE
> .
<VAR
CLASS="PARAMETER"
>buf</VAR
> is a buffer of length
<VAR
CLASS="PARAMETER"
>len</VAR
> bytes which is used to store the
<CODE
CLASS="CONSTANT"
>h_name</CODE
>, <CODE
CLASS="CONSTANT"
>h_aliases</CODE
>, and
<CODE
CLASS="CONSTANT"
>h_addr_list</CODE
> elements of the <SPAN
CLASS="TYPE"
>struct
hostent</SPAN
> returned in <VAR
CLASS="PARAMETER"
>resbuf</VAR
>.
Successful calls to <CODE
CLASS="FUNCTION"
>lwres_gethostbyname_r()</CODE
>
return <VAR
CLASS="PARAMETER"
>resbuf</VAR
>,
which is a pointer to the <SPAN
CLASS="TYPE"
>struct hostent</SPAN
> it created.</P
><P
><CODE
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</CODE
> is a thread-safe function
that performs a reverse lookup of address <VAR
CLASS="PARAMETER"
>addr</VAR
>
which is <VAR
CLASS="PARAMETER"
>len</VAR
> bytes long and is of protocol
family <VAR
CLASS="PARAMETER"
>type</VAR
> — <SPAN
CLASS="TYPE"
>PF_INET</SPAN
> or
<SPAN
CLASS="TYPE"
>PF_INET6</SPAN
>. If an error occurs, the error code is returned
in <VAR
CLASS="PARAMETER"
>*error</VAR
>. The other function parameters are
identical to those in <CODE
CLASS="FUNCTION"
>lwres_gethostbyname_r()</CODE
>.
<VAR
CLASS="PARAMETER"
>resbuf</VAR
> is a pointer to a <SPAN
CLASS="TYPE"
>struct
hostent</SPAN
> which is initialised by a successful call to
<CODE
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</CODE
>.
<VAR
CLASS="PARAMETER"
>buf</VAR
> is a buffer of length
<VAR
CLASS="PARAMETER"
>len</VAR
> bytes which is used to store the
<CODE
CLASS="CONSTANT"
>h_name</CODE
>, <CODE
CLASS="CONSTANT"
>h_aliases</CODE
>, and
<CODE
CLASS="CONSTANT"
>h_addr_list</CODE
> elements of the <SPAN
CLASS="TYPE"
>struct
hostent</SPAN
> returned in <VAR
CLASS="PARAMETER"
>resbuf</VAR
>. Successful
calls to <CODE
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</CODE
> return
<VAR
CLASS="PARAMETER"
>resbuf</VAR
>, which is a pointer to the
<CODE
CLASS="FUNCTION"
>struct hostent()</CODE
> it created.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN191"
></A
><H2
>RETURN VALUES</H2
><P
>The functions
<CODE
CLASS="FUNCTION"
>lwres_gethostbyname()</CODE
>,
<CODE
CLASS="FUNCTION"
>lwres_gethostbyname2()</CODE
>,
<CODE
CLASS="FUNCTION"
>lwres_gethostbyaddr()</CODE
>,
and
<CODE
CLASS="FUNCTION"
>lwres_gethostent()</CODE
>
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
><CODE
CLASS="CONSTANT"
>HOST_NOT_FOUND</CODE
></DT
><DD
><P
>The host or address was not found.</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>TRY_AGAIN</CODE
></DT
><DD
><P
>A recoverable error occurred, e.g., a timeout.
Retrying the lookup may succeed.</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>NO_RECOVERY</CODE
></DT
><DD
><P
>A non-recoverable error occurred.</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>NO_DATA</CODE
></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
><CODE
CLASS="FUNCTION"
>lwres_gethostent()</CODE
>
and
<CODE
CLASS="FUNCTION"
>lwres_gethostent_r()</CODE
>
always return
<SPAN
CLASS="TYPE"
>NULL</SPAN
>.</P
><P
>Successful calls to <CODE
CLASS="FUNCTION"
>lwres_gethostbyname_r()</CODE
> and
<CODE
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</CODE
> return
<VAR
CLASS="PARAMETER"
>resbuf</VAR
>, 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 <VAR
CLASS="PARAMETER"
>buf</VAR
>
was too small to hold the list of addresses and names referenced by
the <CODE
CLASS="CONSTANT"
>h_name</CODE
>, <CODE
CLASS="CONSTANT"
>h_aliases</CODE
>, and
<CODE
CLASS="CONSTANT"
>h_addr_list</CODE
> elements of the <SPAN
CLASS="TYPE"
>struct
hostent</SPAN
>. If <VAR
CLASS="PARAMETER"
>buf</VAR
> was too small, both
<CODE
CLASS="FUNCTION"
>lwres_gethostbyname_r()</CODE
> and
<CODE
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</CODE
> 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
><CODE
CLASS="FUNCTION"
>lwres_gethostbyname()</CODE
>,
<CODE
CLASS="FUNCTION"
>lwres_gethostbyname2()</CODE
>,
<CODE
CLASS="FUNCTION"
>lwres_gethostbyaddr()</CODE
>
and
<CODE
CLASS="FUNCTION"
>lwres_endhostent()</CODE
>
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
<CODE
CLASS="FUNCTION"
>lwres_gethostbyname_r()</CODE
>,
and
<CODE
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</CODE
>
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
>
