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