1152N/A - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") 0N/A - Copyright (C) 2001 Internet Software Consortium. 0N/A - Permission to use, copy, modify, and distribute this software for any 0N/A - purpose with or without fee is hereby granted, provided that the above 0N/A - copyright notice and this permission notice appear in all copies. 0N/A - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 0N/A - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 0N/A - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 0N/A - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 0N/A - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 0N/A - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 0N/A - PERFORMANCE OF THIS SOFTWARE. 0N/A<
meta http-
equiv="Content-Type" content="text/html; charset=ISO-8859-1">
0N/A<
title>lwres_gethostent</
title>
0N/A<
meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
0N/A<
body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><
div class="refentry" lang="en">
0N/A<
a name="id2456972"></
a><
div class="titlepage"></
div>
0N/A<
div class="refnamediv">
0N/A<
p>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</
p>
0N/A<
div class="refsynopsisdiv">
0N/A<
div class="funcsynopsis">
0N/A<
table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><
tr>
0N/A<
td><
code class="funcdef">
0N/A<
b class="fsfunc">lwres_gethostbyname</
b>(</
code></
td>
0N/A<
td>const char *�</
td>
0N/A<
var class="pdparam">name</
var><
code>)</
code>;</
td>
0N/A<
table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
0N/A<
td><
code class="funcdef">
0N/A<
b class="fsfunc">lwres_gethostbyname2</
b>(</
code></
td>
0N/A<
td>const char *�</
td>
0N/A<
var class="pdparam">name</
var>, </
td>
0N/A<
var class="pdparam">af</
var><
code>)</
code>;</
td>
0N/A<
table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
0N/A<
td><
code class="funcdef">
0N/A<
b class="fsfunc">lwres_gethostbyaddr</
b>(</
code></
td>
0N/A<
td>const char *�</
td>
0N/A<
var class="pdparam">addr</
var>, </
td>
132N/A<
var class="pdparam">len</
var>, </
td>
132N/A<
var class="pdparam">type</
var><
code>)</
code>;</
td>
132N/A<
p><
code class="funcdef">
132N/A<
b class="fsfunc">lwres_gethostent</
b>(</
code>void<
code>)</
code>;</
p>
132N/A<
p><
code class="funcdef">
1142N/A<
b class="fsfunc">lwres_sethostent</
b>(</
code>int <
var class="pdparam">stayopen</
var><
code>)</
code>;</
p>
1142N/A<
b class="fsfunc">lwres_endhostent</
b>(</
code>void<
code>)</
code>;</
p>
1142N/A<
table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
1142N/A<
b class="fsfunc">lwres_gethostbyname_r</
b>(</
code></
td>
1142N/A<
var class="pdparam">name</
var>, </
td>
132N/A<
var class="pdparam">resbuf</
var>, </
td>
1142N/A<
var class="pdparam">buf</
var>, </
td>
1142N/A<
var class="pdparam">buflen</
var>, </
td>
1142N/A<
var class="pdparam">error</
var><
code>)</
code>;</
td>
1142N/A<
table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
132N/A<
td><
code class="funcdef">
132N/A<
b class="fsfunc">lwres_gethostbyaddr_r</
b>(</
code></
td>
1142N/A<
var class="pdparam">addr</
var>, </
td>
710N/A<
var class="pdparam">len</
var>, </
td>
710N/A<
var class="pdparam">type</
var>, </
td>
726N/A<
td>struct hostent *�</
td>
1152N/A<
var class="pdparam">resbuf</
var>, </
td>
1142N/A<
var class="pdparam">buf</
var>, </
td>
132N/A<
var class="pdparam">buflen</
var>, </
td>
1142N/A<
var class="pdparam">error</
var><
code>)</
code>;</
td>
1142N/A<
table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
132N/A<
b class="fsfunc">lwres_gethostent_r</
b>(</
code></
td>
132N/A<
td>struct hostent *�</
td>
0N/A<
var class="pdparam">resbuf</
var>, </
td>
0N/A<
var class="pdparam">buf</
var>, </
td>
132N/A<
var class="pdparam">buflen</
var>, </
td>
132N/A<
var class="pdparam">error</
var><
code>)</
code>;</
td>
132N/A<
p><
code class="funcdef">
132N/A<
b class="fsfunc">lwres_sethostent_r</
b>(</
code>int <
var class="pdparam">stayopen</
var><
code>)</
code>;</
p>
132N/A<
p><
code class="funcdef">
132N/A<
b class="fsfunc">lwres_endhostent_r</
b>(</
code>void<
code>)</
code>;</
p>
132N/A<
div class="refsect1" lang="en">
132N/A<
a name="id2514843"></
a><
h2>DESCRIPTION</
h2>
132N/A These functions provide hostname-to-address and
132N/A address-to-hostname lookups by means of the lightweight resolver.
0N/A They are similar to the standard
0N/A <
span class="citerefentry"><
span class="refentrytitle">gethostent</
span>(3)</
span>
0N/A functions provided by most operating systems.
0N/A <
span class="type">struct hostent</
span>
0N/A which is usually defined in
0N/A<
pre class="programlisting">
0N/A char *h_name; /* official name of host */
0N/A char **h_aliases; /* alias list */
0N/A int h_addrtype; /* host address type */
0N/A int h_length; /* length of address */
0N/A char **h_addr_list; /* list of addresses from name server */
0N/A#define h_addr h_addr_list[0] /* address, for backward compatibility */
0N/A The members of this structure are:
0N/A<
div class="variablelist"><
dl>
0N/A<
dt><
span class="term"><
code class="constant">h_name</
code></
span></
dt>
0N/A The official (canonical) name of the host.
0N/A<
dt><
span class="term"><
code class="constant">h_aliases</
code></
span></
dt>
0N/A A NULL-terminated array of alternate names (nicknames) for the
0N/A<
dt><
span class="term"><
code class="constant">h_addrtype</
code></
span></
dt>
0N/A The type of address being returned —
0N/A <
span class="type">PF_INET</
span>
431N/A <
span class="type">PF_INET6</
span>.
431N/A<
dt><
span class="term"><
code class="constant">h_length</
code></
span></
dt>
431N/A The length of the address in bytes.
431N/A<
dt><
span class="term"><
code class="constant">h_addr_list</
code></
span></
dt>
431N/A A <
span class="type">NULL</
span>
0N/A terminated array of network addresses for the host.
0N/A Host addresses are returned in network byte order.
0N/A For backward compatibility with very old software,
0N/A <
code class="constant">h_addr</
code>
0N/A is the first address in
0N/A <
code class="constant">h_addr_list.</
code>
0N/A<
p><
code class="function">lwres_gethostent()</
code>,
0N/A <
code class="function">lwres_sethostent()</
code>,
0N/A <
code class="function">lwres_endhostent()</
code>,
0N/A <
code class="function">lwres_gethostent_r()</
code>,
0N/A <
code class="function">lwres_sethostent_r()</
code>
132N/A <
code class="function">lwres_endhostent_r()</
code>
132N/A provide iteration over the known host entries on systems that
132N/A provide such functionality through facilities like
0N/A or NIS. The lightweight resolver does not currently implement
0N/A these functions; it only provides them as stub functions that always
0N/A<
p><
code class="function">lwres_gethostbyname()</
code>
0N/A and <
code class="function">lwres_gethostbyname2()</
code> look up the
0N/A hostname <
em class="parameter"><
code>name</
code></
em>.
0N/A <
code class="function">lwres_gethostbyname()</
code> always looks for an
0N/A IPv4 address while <
code class="function">lwres_gethostbyname2()</
code>
0N/A looks for an address of protocol family
0N/A <
em class="parameter"><
code>af</
code></
em>: either <
span class="type">PF_INET</
span> or
0N/A <
span class="type">PF_INET6</
span> — IPv4 or IPV6 addresses
0N/A respectively. Successful calls of the functions return a
0N/A <
span class="type">struct hostent</
span>for the name that was looked up.
0N/A <
span class="type">NULL</
span> is returned if the lookups by
0N/A <
code class="function">lwres_gethostbyname()</
code> or
0N/A <
code class="function">lwres_gethostbyname2()</
code> fail.
0N/A Reverse lookups of addresses are performed by
0N/A <
code class="function">lwres_gethostbyaddr()</
code>.
0N/A <
em class="parameter"><
code>addr</
code></
em> is an address of length
0N/A <
em class="parameter"><
code>len</
code></
em> bytes and protocol family
0N/A <
em class="parameter"><
code>type</
code></
em> — <
span class="type">PF_INET</
span> or
0N/A <
span class="type">PF_INET6</
span>.
0N/A <
code class="function">lwres_gethostbyname_r()</
code> is a
0N/A thread-safe function
0N/A for forward lookups. If an error occurs, an error code is returned in
0N/A <
em class="parameter"><
code>*error</
code></
em>.
0N/A <
em class="parameter"><
code>resbuf</
code></
em> is a pointer to a
0N/A <
span class="type">struct hostent</
span> which is initialised by a successful call to
0N/A <
code class="function">lwres_gethostbyname_r()</
code>.
0N/A <
em class="parameter"><
code>buf</
code></
em> is a buffer of length
0N/A <
em class="parameter"><
code>len</
code></
em> bytes which is used to store the
0N/A <
code class="constant">h_name</
code>, <
code class="constant">h_aliases</
code>, and
0N/A <
code class="constant">h_addr_list</
code> elements of the
0N/A <
span class="type">struct hostent</
span> returned in <
em class="parameter"><
code>resbuf</
code></
em>.
0N/A Successful calls to <
code class="function">lwres_gethostbyname_r()</
code>
0N/A return <
em class="parameter"><
code>resbuf</
code></
em>,
0N/A which is a pointer to the <
span class="type">struct hostent</
span> it created.
0N/A<
p><
code class="function">lwres_gethostbyaddr_r()</
code>
0N/A is a thread-safe function
0N/A that performs a reverse lookup of address <
em class="parameter"><
code>addr</
code></
em>
0N/A which is <
em class="parameter"><
code>len</
code></
em> bytes long and is of
0N/A family <
em class="parameter"><
code>type</
code></
em> — <
span class="type">PF_INET</
span> or
0N/A <
span class="type">PF_INET6</
span>. If an error occurs, the error code is returned
0N/A in <
em class="parameter"><
code>*error</
code></
em>. The other function
0N/A identical to those in <
code class="function">lwres_gethostbyname_r()</
code>.
0N/A <
em class="parameter"><
code>resbuf</
code></
em> is a pointer to a
0N/A <
span class="type">struct hostent</
span> which is initialised by a successful call to
0N/A <
code class="function">lwres_gethostbyaddr_r()</
code>.
0N/A <
em class="parameter"><
code>buf</
code></
em> is a buffer of length
0N/A <
em class="parameter"><
code>len</
code></
em> bytes which is used to store the
0N/A <
code class="constant">h_name</
code>, <
code class="constant">h_aliases</
code>, and
0N/A <
code class="constant">h_addr_list</
code> elements of the
0N/A <
span class="type">struct hostent</
span> returned in <
em class="parameter"><
code>resbuf</
code></
em>.
0N/A Successful calls to <
code class="function">lwres_gethostbyaddr_r()</
code> return
0N/A <
em class="parameter"><
code>resbuf</
code></
em>, which is a pointer to the
0N/A <
code class="function">struct hostent()</
code> it created.
0N/A<
div class="refsect1" lang="en">
0N/A<
a name="id2515262"></
a><
h2>RETURN VALUES</
h2>
0N/A <
code class="function">lwres_gethostbyname()</
code>,
0N/A <
code class="function">lwres_gethostbyname2()</
code>,
0N/A <
code class="function">lwres_gethostbyaddr()</
code>,
0N/A <
code class="function">lwres_gethostent()</
code>
0N/A return NULL to indicate an error. In this case the global variable
0N/A <
span class="type">lwres_h_errno</
span>
0N/A will contain one of the following error codes defined in
0N/A<
div class="variablelist"><
dl>
0N/A<
dt><
span class="term"><
code class="constant">HOST_NOT_FOUND</
code></
span></
dt>
0N/A The host or address was not found.
0N/A<
dt><
span class="term"><
code class="constant">TRY_AGAIN</
code></
span></
dt>
0N/A A recoverable error occurred,
e.g., a timeout.
0N/A Retrying the lookup may succeed.
0N/A<
dt><
span class="term"><
code class="constant">NO_RECOVERY</
code></
span></
dt>
0N/A A non-recoverable error occurred.
0N/A<
dt><
span class="term"><
code class="constant">NO_DATA</
code></
span></
dt>
0N/A The name exists, but has no address information
0N/A associated with it (or vice versa in the case
0N/A of a reverse lookup). The code NO_ADDRESS
0N/A is accepted as a synonym for NO_DATA for backwards
0N/A<
p><
span class="citerefentry"><
span class="refentrytitle">lwres_hstrerror</
span>(3)</
span>
0N/A translates these error codes to suitable error messages.
0N/A<
p><
code class="function">lwres_gethostent()</
code>
0N/A and <
code class="function">lwres_gethostent_r()</
code>
0N/A always return <
span class="type">NULL</
span>.
132N/A Successful calls to <
code class="function">lwres_gethostbyname_r()</
code> and
132N/A <
code class="function">lwres_gethostbyaddr_r()</
code> return
132N/A <
em class="parameter"><
code>resbuf</
code></
em>, a pointer to the
132N/A <
span class="type">struct hostent</
span> that was initialised by these functions. They return
132N/A <
span class="type">NULL</
span> if the lookups fail or if <
em class="parameter"><
code>buf</
code></
em>
132N/A was too small to hold the list of addresses and names referenced by
132N/A the <
code class="constant">h_name</
code>, <
code class="constant">h_aliases</
code>, and
0N/A <
code class="constant">h_addr_list</
code> elements of the
132N/A <
span class="type">struct hostent</
span>.
132N/A If <
em class="parameter"><
code>buf</
code></
em> was too small, both
0N/A <
code class="function">lwres_gethostbyname_r()</
code> and
0N/A <
code class="function">lwres_gethostbyaddr_r()</
code> set the global
132N/A <
span class="type">errno</
span> to <
span class="errorcode">ERANGE</
span>.
132N/A<
div class="refsect1" lang="en">
132N/A<
a name="id2515496"></
a><
h2>SEE ALSO</
h2>
0N/A<
p><
span class="citerefentry"><
span class="refentrytitle">gethostent</
span>(3)</
span>,
132N/A <
span class="citerefentry"><
span class="refentrytitle">lwres_getipnode</
span>(3)</
span>,
132N/A <
span class="citerefentry"><
span class="refentrytitle">lwres_hstrerror</
span>(3)</
span>
132N/A<
div class="refsect1" lang="en">
147N/A<
a name="id2515530"></
a><
h2>BUGS</
h2>
0N/A<
p><
code class="function">lwres_gethostbyname()</
code>,
0N/A <
code class="function">lwres_gethostbyname2()</
code>,
0N/A <
code class="function">lwres_gethostbyaddr()</
code>
0N/A <
code class="function">lwres_endhostent()</
code>
0N/A are not thread safe; they return pointers to static data and
0N/A provide error codes through a global variable.
0N/A Thread-safe versions for name and address lookup are provided by
0N/A <
code class="function">lwres_gethostbyname_r()</
code>,
0N/A <
code class="function">lwres_gethostbyaddr_r()</
code>
0N/A The resolver daemon does not currently support any non-DNS
0N/A name services such as
0N/A <
span class="type">NIS</
span>,
0N/A consequently the above functions don't, either.