lwres_gethostent.html [plain text]
<!--
- 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
>