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