lwres_gethostent.html revision 8de7014e56565605a51898a2a33a8b08fd3f1e57
363N/A<!--
363N/A - Copyright (C) 2000, 2001 Internet Software Consortium.
363N/A -
363N/A - Permission to use, copy, modify, and distribute this software for any
363N/A - purpose with or without fee is hereby granted, provided that the above
363N/A - copyright notice and this permission notice appear in all copies.
363N/A -
363N/A - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
363N/A - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
363N/A - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
363N/A - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
363N/A - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
363N/A - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
363N/A - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
363N/A - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
363N/A-->
363N/A<HTML
363N/A><HEAD
363N/A><TITLE
363N/A>lwres_gethostent</TITLE
3817N/A><META
363N/ANAME="GENERATOR"
363N/ACONTENT="Modular DocBook HTML Stylesheet Version 1.61
363N/A"></HEAD
2221N/A><BODY
2221N/ACLASS="REFENTRY"
363N/ABGCOLOR="#FFFFFF"
363N/ATEXT="#000000"
364N/ALINK="#0000FF"
363N/AVLINK="#840084"
363N/AALINK="#0000FF"
3062N/A><H1
2221N/A><A
363N/ANAME="AEN1"
844N/A>lwres_gethostent</A
3062N/A></H1
363N/A><DIV
2931N/ACLASS="REFNAMEDIV"
363N/A><A
3817N/ANAME="AEN8"
3817N/A></A
363N/A><H2
695N/A>Name</H2
365N/A>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&nbsp;--&nbsp;lightweight resolver get network host entry</DIV
363N/A><DIV
363N/ACLASS="REFSYNOPSISDIV"
363N/A><A
363N/ANAME="AEN21"
363N/A></A
2221N/A><H2
363N/A>Synopsis</H2
363N/A><DIV
4662N/ACLASS="FUNCSYNOPSIS"
695N/A><A
363N/ANAME="AEN22"
363N/A></A
363N/A><P
4250N/A></P
814N/A><PRE
363N/ACLASS="FUNCSYNOPSISINFO"
4820N/A>#include &lt;lwres/netdb.h&gt;</PRE
791N/A><P
791N/A><CODE
791N/A><CODE
4662N/ACLASS="FUNCDEF"
363N/A>struct hostent *
3062N/Alwres_gethostbyname</CODE
3062N/A>(const char *name);</CODE
3062N/A></P
3062N/A><P
363N/A><CODE
3062N/A><CODE
363N/ACLASS="FUNCDEF"
363N/A>struct hostent *
363N/Alwres_gethostbyname2</CODE
363N/A>(const char *name, int af);</CODE
363N/A></P
363N/A><P
363N/A><CODE
363N/A><CODE
363N/ACLASS="FUNCDEF"
363N/A>struct hostent *
363N/Alwres_gethostbyaddr</CODE
2221N/A>(const char *addr, int len, int type);</CODE
2221N/A></P
2221N/A><P
2221N/A><CODE
2221N/A><CODE
2221N/ACLASS="FUNCDEF"
2221N/A>struct hostent *
363N/Alwres_gethostent</CODE
2221N/A>(void);</CODE
2221N/A></P
363N/A><P
2221N/A><CODE
363N/A><CODE
363N/ACLASS="FUNCDEF"
363N/A>void
363N/Alwres_sethostent</CODE
5123N/A>(int stayopen);</CODE
5123N/A></P
5123N/A><P
5123N/A><CODE
363N/A><CODE
695N/ACLASS="FUNCDEF"
695N/A>void
363N/Alwres_endhostent</CODE
363N/A>(void);</CODE
363N/A></P
363N/A><P
363N/A><CODE
363N/A><CODE
3477N/ACLASS="FUNCDEF"
3477N/A>struct hostent *
363N/Alwres_gethostbyname_r</CODE
363N/A>(const char *name, struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
363N/A></P
363N/A><P
695N/A><CODE
363N/A><CODE
363N/ACLASS="FUNCDEF"
363N/A>struct hostent *
363N/Alwres_gethostbyaddr_r</CODE
363N/A>(const char *addr, int len, int type, struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
363N/A></P
4514N/A><P
2877N/A><CODE
363N/A><CODE
363N/ACLASS="FUNCDEF"
363N/A>struct hostent *
363N/Alwres_gethostent_r</CODE
363N/A>(struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
363N/A></P
363N/A><P
4337N/A><CODE
4337N/A><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"
>&lt;namedb.h&gt;</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 &mdash;
<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
>
&mdash; 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
> &mdash;
<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
> &mdash;
<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"
>&lt;lwres/netdb.h&gt;</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
>.&#13;</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
>.&#13;</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
>