lwres_gethostent.html revision 75c0816e8295e180f4bc7f10db3d0d880383bc1c
d4a4220020a793457962e3784641b0b14caaed5fjwoolley - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
2a6c49cfaef5979a5a06098f3ce987cd76769409manoj - Copyright (C) 2001 Internet Software Consortium.
2a6c49cfaef5979a5a06098f3ce987cd76769409manoj - Permission to use, copy, modify, and distribute this software for any
df14f0d3a5191cdd7c4bb5b03acd135d43a6f51brbb - purpose with or without fee is hereby granted, provided that the above
df14f0d3a5191cdd7c4bb5b03acd135d43a6f51brbb - copyright notice and this permission notice appear in all copies.
571760de5e60c0b459cb11be45507b923cd023eejwoolley - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
571760de5e60c0b459cb11be45507b923cd023eejwoolley - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
9180a5933673ffb1af633c255ceee029340f3b1erbb - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
bcb6e1be6041dfeb549c8ea8d37f97ad4e90a0c3rbb - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
9bd71e35f5d26d26d23fe3a677401828e842ed72wrowe - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
2900ab946a2d76b73a14cebfe2985d253f01c967stoddard - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
a548c09e6a8ca1b059d0e93b5256c6ccb2b3c3cdrbb - PERFORMANCE OF THIS SOFTWARE.
a548c09e6a8ca1b059d0e93b5256c6ccb2b3c3cdrbb<!-- $Id: lwres_gethostent.html,v 1.16 2005/05/13 03:14:14 marka Exp $ -->
35330e0d79ceb8027223bbb8330a381b1f989d6etrawick<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
8dd4618c4709236b4ea297d7250d282e463ce2d8rbb<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
2deb319e6b3de239f45c16a3e9e836d44f1f7108rbb<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
af4c982a7cf4515f124935f99a329744035fc699slive<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>
af4c982a7cf4515f124935f99a329744035fc699slive<pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre>
af4c982a7cf4515f124935f99a329744035fc699slive<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
531c23ff01a2489646f0a2029097013b328d935agsteinstruct hostent *
b84f66c93f820824b1d5455181f55598b766319cwrowe<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
b84f66c93f820824b1d5455181f55598b766319cwrowestruct hostent *
b84f66c93f820824b1d5455181f55598b766319cwrowe<b class="fsfunc">lwres_gethostbyname2</b>(</code></td>
bf9acc131271d18db51d30ace549d3c3b6a2b9fbrbb<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
bf9acc131271d18db51d30ace549d3c3b6a2b9fbrbbstruct hostent *
dc96a5e6f9af3c514df4c61ab9468fcf97f9846fwrowestruct hostent *
dc96a5e6f9af3c514df4c61ab9468fcf97f9846fwrowe<b class="fsfunc">lwres_gethostent</b>(</code>void<code>)</code>;</p>
dc96a5e6f9af3c514df4c61ab9468fcf97f9846fwrowe<b class="fsfunc">lwres_sethostent</b>(</code>int <var class="pdparam">stayopen</var><code>)</code>;</p>
dc96a5e6f9af3c514df4c61ab9468fcf97f9846fwrowe<b class="fsfunc">lwres_endhostent</b>(</code>void<code>)</code>;</p>
dc96a5e6f9af3c514df4c61ab9468fcf97f9846fwrowe<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
dc96a5e6f9af3c514df4c61ab9468fcf97f9846fwrowestruct hostent *
dc96a5e6f9af3c514df4c61ab9468fcf97f9846fwrowe<b class="fsfunc">lwres_gethostbyname_r</b>(</code></td>
d4a4220020a793457962e3784641b0b14caaed5fjwoolley<var class="pdparam">error</var><code>)</code>;</td>
bca84f0b0ca4f3466ac2f845f1bdcdede7f34d91rbb<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
809cf6f87f7a07b348f6d69961834923bc16313egsteinstruct hostent *
410912d9cb56a09a74f8655647ed9e81d49023f4gregames<b class="fsfunc">lwres_gethostbyaddr_r</b>(</code></td>
1b9744b72f26e9a0e935f9c08d49feb1fcce72f9jwoolley<var class="pdparam">error</var><code>)</code>;</td>
1b9744b72f26e9a0e935f9c08d49feb1fcce72f9jwoolley<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
1b9744b72f26e9a0e935f9c08d49feb1fcce72f9jwoolleystruct hostent *
1b9744b72f26e9a0e935f9c08d49feb1fcce72f9jwoolley<b class="fsfunc">lwres_gethostent_r</b>(</code></td>
1e585ba09ea32272e63c4c39c35491e975d21d98stoddard<b class="fsfunc">lwres_sethostent_r</b>(</code>int <var class="pdparam">stayopen</var><code>)</code>;</p>
0bff2f28ef945280c17099c142126178a78e1e54manoj<b class="fsfunc">lwres_endhostent_r</b>(</code>void<code>)</code>;</p>
447c6ce3ff08073c44f6785d5256271fcb877512wrowe These functions provide hostname-to-address and
447c6ce3ff08073c44f6785d5256271fcb877512wrowe address-to-hostname lookups by means of the lightweight resolver.
447c6ce3ff08073c44f6785d5256271fcb877512wrowe They are similar to the standard
447c6ce3ff08073c44f6785d5256271fcb877512wrowe <span class="citerefentry"><span class="refentrytitle">gethostent</span>(3)</span>
cf6bf6c34c936e6a6fe731dbce4a5c3c8bf8e9a3gstein functions provided by most operating systems.
3bb28269556842ebf8888208fd0c7a7f3e343186jerenkrantz which is usually defined in
dd4713dc5b186f4d1be7b88f86608fdb84cbe5d5gsteinstruct hostent {
0eb7ca6cf812d98c534661ac474e873a32bf6325gstein char *h_name; /* official name of host */
cf6bf6c34c936e6a6fe731dbce4a5c3c8bf8e9a3gstein char **h_aliases; /* alias list */
8d07897b52e3b7055874501f8a499e75800db206gstein int h_addrtype; /* host address type */
8d07897b52e3b7055874501f8a499e75800db206gstein int h_length; /* length of address */
db3ccce11afac4fc1d4f51a65424412f7480c46cgstein char **h_addr_list; /* list of addresses from name server */
79d5106a9b65b956d646f5daae4b94bc79e315b8trawick#define h_addr h_addr_list[0] /* address, for backward compatibility */
6fa71a1bd8c61518b05f5798a7a1594c270e78afrbb The members of this structure are:
14cccaddba3a9263cf0d0ddc311e18f3e3dc9b0fgstein<dt><span class="term"><code class="constant">h_name</code></span></dt>
14cccaddba3a9263cf0d0ddc311e18f3e3dc9b0fgstein The official (canonical) name of the host.
14cccaddba3a9263cf0d0ddc311e18f3e3dc9b0fgstein<dt><span class="term"><code class="constant">h_aliases</code></span></dt>
823c303d33c9e637a83d82208bcbafaf5f532d7bgstein A NULL-terminated array of alternate names (nicknames) for the
e636eba7474e0010b5c7198af1c2fe5ad8652dbbmanoj<dt><span class="term"><code class="constant">h_addrtype</code></span></dt>
281da4c02cf40c663298ded7e4e5b913a8f8b814gstein The type of address being returned —
2f728b2e8555fee1b7cc11e886488692f2575fbddougm<dt><span class="term"><code class="constant">h_length</code></span></dt>
114cc51b75ed89d5ab2f39b85ba7d472293f3dedtrawick The length of the address in bytes.
114cc51b75ed89d5ab2f39b85ba7d472293f3dedtrawick<dt><span class="term"><code class="constant">h_addr_list</code></span></dt>
60d567a0c2aae815ee6fc20c0d65032bea52c92cwrowe terminated array of network addresses for the host.
60d567a0c2aae815ee6fc20c0d65032bea52c92cwrowe Host addresses are returned in network byte order.
60d567a0c2aae815ee6fc20c0d65032bea52c92cwrowe For backward compatibility with very old software,
60d567a0c2aae815ee6fc20c0d65032bea52c92cwrowe is the first address in
28d1da9ca818f831ea491f110dafcc10f7f07050coar provide iteration over the known host entries on systems that
64ad864fa0f4493eebb181e393b40a8a90beccb9coar provide such functionality through facilities like
64ad864fa0f4493eebb181e393b40a8a90beccb9coar or NIS. The lightweight resolver does not currently implement
28d1da9ca818f831ea491f110dafcc10f7f07050coar these functions; it only provides them as stub functions that always
64ad864fa0f4493eebb181e393b40a8a90beccb9coar return failure.
64ad864fa0f4493eebb181e393b40a8a90beccb9coar and <code class="function">lwres_gethostbyname2()</code> look up the
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <code class="function">lwres_gethostbyname()</code> always looks for an
64ad864fa0f4493eebb181e393b40a8a90beccb9coar IPv4 address while <code class="function">lwres_gethostbyname2()</code>
64ad864fa0f4493eebb181e393b40a8a90beccb9coar looks for an address of protocol family
28d1da9ca818f831ea491f110dafcc10f7f07050coar <em class="parameter"><code>af</code></em>: either <span class="type">PF_INET</span> or
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <span class="type">PF_INET6</span> — IPv4 or IPV6 addresses
64ad864fa0f4493eebb181e393b40a8a90beccb9coar respectively. Successful calls of the functions return a
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <span class="type">struct hostent</span>for the name that was looked up.
28d1da9ca818f831ea491f110dafcc10f7f07050coar <span class="type">NULL</span> is returned if the lookups by
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <code class="function">lwres_gethostbyname2()</code> fail.
64ad864fa0f4493eebb181e393b40a8a90beccb9coar Reverse lookups of addresses are performed by
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <em class="parameter"><code>addr</code></em> is an address of length
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <em class="parameter"><code>len</code></em> bytes and protocol family
28d1da9ca818f831ea491f110dafcc10f7f07050coar <em class="parameter"><code>type</code></em> — <span class="type">PF_INET</span> or
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <code class="function">lwres_gethostbyname_r()</code> is a
64ad864fa0f4493eebb181e393b40a8a90beccb9coar thread-safe function
28d1da9ca818f831ea491f110dafcc10f7f07050coar for forward lookups. If an error occurs, an error code is returned in
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <em class="parameter"><code>resbuf</code></em> is a pointer to a
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <span class="type">struct hostent</span> which is initialised by a successful call to
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <em class="parameter"><code>buf</code></em> is a buffer of length
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <em class="parameter"><code>len</code></em> bytes which is used to store the
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and
28d1da9ca818f831ea491f110dafcc10f7f07050coar <code class="constant">h_addr_list</code> elements of the
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <span class="type">struct hostent</span> returned in <em class="parameter"><code>resbuf</code></em>.
64ad864fa0f4493eebb181e393b40a8a90beccb9coar Successful calls to <code class="function">lwres_gethostbyname_r()</code>
28d1da9ca818f831ea491f110dafcc10f7f07050coar which is a pointer to the <span class="type">struct hostent</span> it created.
64ad864fa0f4493eebb181e393b40a8a90beccb9coar<p><code class="function">lwres_gethostbyaddr_r()</code>
64ad864fa0f4493eebb181e393b40a8a90beccb9coar is a thread-safe function
28d1da9ca818f831ea491f110dafcc10f7f07050coar that performs a reverse lookup of address <em class="parameter"><code>addr</code></em>
64ad864fa0f4493eebb181e393b40a8a90beccb9coar which is <em class="parameter"><code>len</code></em> bytes long and is of
64ad864fa0f4493eebb181e393b40a8a90beccb9coar family <em class="parameter"><code>type</code></em> — <span class="type">PF_INET</span> or
28d1da9ca818f831ea491f110dafcc10f7f07050coar <span class="type">PF_INET6</span>. If an error occurs, the error code is returned
64ad864fa0f4493eebb181e393b40a8a90beccb9coar in <em class="parameter"><code>*error</code></em>. The other function
64ad864fa0f4493eebb181e393b40a8a90beccb9coar parameters are
64ad864fa0f4493eebb181e393b40a8a90beccb9coar identical to those in <code class="function">lwres_gethostbyname_r()</code>.
28d1da9ca818f831ea491f110dafcc10f7f07050coar <em class="parameter"><code>resbuf</code></em> is a pointer to a
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <span class="type">struct hostent</span> which is initialised by a successful call to
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <em class="parameter"><code>buf</code></em> is a buffer of length
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <em class="parameter"><code>len</code></em> bytes which is used to store the
28d1da9ca818f831ea491f110dafcc10f7f07050coar <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <code class="constant">h_addr_list</code> elements of the
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <span class="type">struct hostent</span> returned in <em class="parameter"><code>resbuf</code></em>.
64ad864fa0f4493eebb181e393b40a8a90beccb9coar Successful calls to <code class="function">lwres_gethostbyaddr_r()</code> return
28d1da9ca818f831ea491f110dafcc10f7f07050coar <em class="parameter"><code>resbuf</code></em>, which is a pointer to the
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <code class="function">struct hostent()</code> it created.
64ad864fa0f4493eebb181e393b40a8a90beccb9coar The functions
64ad864fa0f4493eebb181e393b40a8a90beccb9coar return NULL to indicate an error. In this case the global variable
64ad864fa0f4493eebb181e393b40a8a90beccb9coar will contain one of the following error codes defined in
28d1da9ca818f831ea491f110dafcc10f7f07050coar<dt><span class="term"><code class="constant">HOST_NOT_FOUND</code></span></dt>
64ad864fa0f4493eebb181e393b40a8a90beccb9coar The host or address was not found.
28d1da9ca818f831ea491f110dafcc10f7f07050coar<dt><span class="term"><code class="constant">TRY_AGAIN</code></span></dt>
64ad864fa0f4493eebb181e393b40a8a90beccb9coar A recoverable error occurred, e.g., a timeout.
64ad864fa0f4493eebb181e393b40a8a90beccb9coar Retrying the lookup may succeed.
64ad864fa0f4493eebb181e393b40a8a90beccb9coar<dt><span class="term"><code class="constant">NO_RECOVERY</code></span></dt>
64ad864fa0f4493eebb181e393b40a8a90beccb9coar A non-recoverable error occurred.
64ad864fa0f4493eebb181e393b40a8a90beccb9coar<dt><span class="term"><code class="constant">NO_DATA</code></span></dt>
64ad864fa0f4493eebb181e393b40a8a90beccb9coar The name exists, but has no address information
28d1da9ca818f831ea491f110dafcc10f7f07050coar associated with it (or vice versa in the case
64ad864fa0f4493eebb181e393b40a8a90beccb9coar of a reverse lookup). The code NO_ADDRESS
64ad864fa0f4493eebb181e393b40a8a90beccb9coar is accepted as a synonym for NO_DATA for backwards
64ad864fa0f4493eebb181e393b40a8a90beccb9coar compatibility.
28d1da9ca818f831ea491f110dafcc10f7f07050coar<p><span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>
64ad864fa0f4493eebb181e393b40a8a90beccb9coar translates these error codes to suitable error messages.
28d1da9ca818f831ea491f110dafcc10f7f07050coar Successful calls to <code class="function">lwres_gethostbyname_r()</code> and
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <code class="function">lwres_gethostbyaddr_r()</code> return
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <em class="parameter"><code>resbuf</code></em>, a pointer to the
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <span class="type">struct hostent</span> that was initialised by these functions. They return
28d1da9ca818f831ea491f110dafcc10f7f07050coar <span class="type">NULL</span> if the lookups fail or if <em class="parameter"><code>buf</code></em>
64ad864fa0f4493eebb181e393b40a8a90beccb9coar was too small to hold the list of addresses and names referenced by
6694e265e9a71ceaedbe1f1aa4db4d9ba42fb866wrowe the <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <code class="constant">h_addr_list</code> elements of the
64ad864fa0f4493eebb181e393b40a8a90beccb9coar If <em class="parameter"><code>buf</code></em> was too small, both
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <code class="function">lwres_gethostbyname_r()</code> and
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <code class="function">lwres_gethostbyaddr_r()</code> set the global
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <span class="type">errno</span> to <span class="errorcode">ERANGE</span>.
64ad864fa0f4493eebb181e393b40a8a90beccb9coar<p><span class="citerefentry"><span class="refentrytitle">gethostent</span>(3)</span>,
28d1da9ca818f831ea491f110dafcc10f7f07050coar <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>,
64ad864fa0f4493eebb181e393b40a8a90beccb9coar <span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>
64ad864fa0f4493eebb181e393b40a8a90beccb9coar are not thread safe; they return pointers to static data and
64ad864fa0f4493eebb181e393b40a8a90beccb9coar provide error codes through a global variable.
28d1da9ca818f831ea491f110dafcc10f7f07050coar Thread-safe versions for name and address lookup are provided by
28d1da9ca818f831ea491f110dafcc10f7f07050coar respectively.
64ad864fa0f4493eebb181e393b40a8a90beccb9coar The resolver daemon does not currently support any non-DNS
28d1da9ca818f831ea491f110dafcc10f7f07050coar name services such as
28d1da9ca818f831ea491f110dafcc10f7f07050coar consequently the above functions don't, either.