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