lwres_getipnode.html revision ea94d370123a5892f6c47a97f21d1b28d44bb168
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński - Permission to use, copy, modify, and/or distribute this software for any
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński - purpose with or without fee is hereby granted, provided that the above
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński - copyright notice and this permission notice appear in all copies.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
3a3365c39fe3932d005ae1aa4324ef48606f5e18Krzysztof Kosiński - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński - PERFORMANCE OF THIS SOFTWARE.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<a name="id2476275"></a><div class="titlepage"></div>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<p>lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent — lightweight resolver nodename / address translation API</p>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosińskistruct hostent *
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<b class="fsfunc">lwres_getipnodebyname</b>(</code></td>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<var class="pdparam">error_num</var><code>)</code>;</td>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosińskistruct hostent *
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<b class="fsfunc">lwres_getipnodebyaddr</b>(</code></td>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<var class="pdparam">error_num</var><code>)</code>;</td>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<b class="fsfunc">lwres_freehostent</b>(</code></td>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<var class="pdparam">he</var><code>)</code>;</td>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<a name="id2543432"></a><h2>DESCRIPTION</h2>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński These functions perform thread safe, protocol independent
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński nodename-to-address and address-to-nodename
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński translation as defined in RFC2553.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński which is defined in
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosińskistruct hostent {
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński char *h_name; /* official name of host */
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński char **h_aliases; /* alias list */
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński int h_addrtype; /* host address type */
3a3365c39fe3932d005ae1aa4324ef48606f5e18Krzysztof Kosiński int h_length; /* length of address */
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński char **h_addr_list; /* list of addresses from name server */
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński#define h_addr h_addr_list[0] /* address, for backward compatibility */
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński The members of this structure are:
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">h_name</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński The official (canonical) name of the host.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">h_aliases</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński A NULL-terminated array of alternate names (nicknames) for the
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">h_addrtype</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński The type of address being returned - usually
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">h_length</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński The length of the address in bytes.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">h_addr_list</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński terminated array of network addresses for the host.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński Host addresses are returned in network byte order.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<p><code class="function">lwres_getipnodebyname()</code>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński looks up addresses of protocol family <em class="parameter"><code>af</code></em>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński for the hostname <em class="parameter"><code>name</code></em>. The
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <em class="parameter"><code>flags</code></em> parameter contains ORed flag bits
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński to specify the types of addresses that are searched for, and the
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński types of addresses that are returned. The flag bits are:
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">AI_V4MAPPED</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński This is used with an
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <em class="parameter"><code>af</code></em>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński of AF_INET6, and causes IPv4 addresses to be returned as
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński IPv6 addresses.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">AI_ALL</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński This is used with an
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <em class="parameter"><code>af</code></em>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński If AI_V4MAPPED is also set, the IPv4 addresses are return as
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński IPv6 addresses.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">AI_ADDRCONFIG</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński Only return an IPv6 or IPv4 address if here is an active network
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński interface of that type. This is not currently implemented
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński in the BIND 9 lightweight resolver, and the flag is ignored.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">AI_DEFAULT</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński This default sets the
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <code class="constant">AI_V4MAPPED</code>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <code class="constant">AI_ADDRCONFIG</code>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<p><code class="function">lwres_getipnodebyaddr()</code>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński performs a reverse lookup of address <em class="parameter"><code>src</code></em>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński which is <em class="parameter"><code>len</code></em> bytes long.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <em class="parameter"><code>af</code></em> denotes the protocol family, typically
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <span class="type">PF_INET</span> or <span class="type">PF_INET6</span>.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<p><code class="function">lwres_freehostent()</code>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński releases all the memory associated with the <span class="type">struct
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński hostent</span> pointer <em class="parameter"><code>he</code></em>. Any memory
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński allocated for the <code class="constant">h_name</code>,
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <code class="constant">h_addr_list</code> and
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <code class="constant">h_aliases</code> is freed, as is the memory for
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński the <span class="type">hostent</span> structure itself.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<a name="id2543690"></a><h2>RETURN VALUES</h2>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński If an error occurs,
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <code class="function">lwres_getipnodebyname()</code>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <code class="function">lwres_getipnodebyaddr()</code>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <em class="parameter"><code>*error_num</code></em>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński to an appropriate error code and the function returns a
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński The error codes and their meanings are defined in
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński <code class="filename"><lwres/netdb.h></code>:
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">HOST_NOT_FOUND</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński No such host is known.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">NO_ADDRESS</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński The server recognised the request and the name but no address is
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński available. Another type of request to the name server for the
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński domain might return an answer.
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">TRY_AGAIN</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński A temporary and possibly transient error occurred, such as a
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński failure of a server to respond. The request may succeed if
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<dt><span class="term"><code class="constant">NO_RECOVERY</code></span></dt>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński An unexpected failure occurred, and retrying the request
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński<p><span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>
d1bde559850436556ebee2e70e10f1cfc8aff636Krzysztof Kosiński translates these error codes to suitable error messages.