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