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