lwres_getipnode.html revision 7911e6f9de303bca5a3d8b34f4330c8f7cecffae
d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Copyright (C) 2000, 2001, 2003-2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - This Source Code Form is subject to the terms of the Mozilla Public
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - License, v. 2.0. If a copy of the MPL was not distributed with this
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - file, You can obtain one at http://mozilla.org/MPL/2.0/.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1"></a><div class="titlepage"></div>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_getipnodebyname,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_getipnodebyaddr,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_freehostent
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User — lightweight resolver nodename / address translation API
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinstruct hostent *
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_getipnodebyname</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>const char *<var class="pdparam">name</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>int <var class="pdparam">flags</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>int *<var class="pdparam">error_num</var><code>)</code>;</td>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinstruct hostent *
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_getipnodebyaddr</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>const void *<var class="pdparam">src</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>size_t <var class="pdparam">len</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>int *<var class="pdparam">error_num</var><code>)</code>;</td>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_freehostent</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>struct hostent *<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:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="variablelist"><dl class="variablelist">
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.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <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:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="variablelist"><dl class="variablelist">
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
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <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>.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <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>:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<div class="variablelist"><dl class="variablelist">
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.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">lwres_hstrerror</span>(3)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein translates these error codes to suitable error messages.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">lwres_gethostent</span>(3)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">lwres_getaddrinfo</span>(3)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">lwres_getnameinfo</span>(3)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">lwres_hstrerror</span>(3)