contrib/bind/lib/lwres/man/lwres_getipnode.html

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and/or distribute this software for any
   6  - purpose with or without fee is hereby granted, provided that the above
   7  - copyright notice and this permission notice appear in all copies.
   8  -
   9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17 <!-- $Id: lwres_getipnode.html,v 1.25.214.1.2.1 2009/12/31 23:47:14 tbox Exp $ -->
  18 <html>
  19 <head>
  20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  21 <title>lwres_getipnode</title>
  22 <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
  23 </head>
  24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
  25 <a name="id2476267"></a><div class="titlepage"></div>
  26 <div class="refnamediv">
  27 <h2>Name</h2>
  28 <p>lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent &#8212; lightweight resolver nodename / address translation API</p>
  29 </div>
  30 <div class="refsynopsisdiv">
  31 <h2>Synopsis</h2>
  32 <div class="funcsynopsis">
  33 <pre class="funcsynopsisinfo">#include &lt;lwres/netdb.h&gt;</pre>
  34 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  35 <tr>
  36 <td><code class="funcdef">
  37 struct hostent *
  38 <b class="fsfunc">lwres_getipnodebyname</b>(</code></td>
  39 <td>const char * </td>
  40 <td>
  41 <var class="pdparam">name</var>, </td>
  42 </tr>
  43 <tr>
  44 <td> </td>
  45 <td>int  </td>
  46 <td>
  47 <var class="pdparam">af</var>, </td>
  48 </tr>
  49 <tr>
  50 <td> </td>
  51 <td>int  </td>
  52 <td>
  53 <var class="pdparam">flags</var>, </td>
  54 </tr>
  55 <tr>
  56 <td> </td>
  57 <td>int * </td>
  58 <td>
  59 <var class="pdparam">error_num</var><code>)</code>;</td>
  60 </tr>
  61 </table>
  62 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  63 <tr>
  64 <td><code class="funcdef">
  65 struct hostent *
  66 <b class="fsfunc">lwres_getipnodebyaddr</b>(</code></td>
  67 <td>const void * </td>
  68 <td>
  69 <var class="pdparam">src</var>, </td>
  70 </tr>
  71 <tr>
  72 <td> </td>
  73 <td>size_t  </td>
  74 <td>
  75 <var class="pdparam">len</var>, </td>
  76 </tr>
  77 <tr>
  78 <td> </td>
  79 <td>int  </td>
  80 <td>
  81 <var class="pdparam">af</var>, </td>
  82 </tr>
  83 <tr>
  84 <td> </td>
  85 <td>int * </td>
  86 <td>
  87 <var class="pdparam">error_num</var><code>)</code>;</td>
  88 </tr>
  89 </table>
  90 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr>
  91 <td><code class="funcdef">
  92 void
  93 <b class="fsfunc">lwres_freehostent</b>(</code></td>
  94 <td>struct hostent * </td>
  95 <td>
  96 <var class="pdparam">he</var><code>)</code>;</td>
  97 </tr></table>
  98 </div>
  99 </div>
 100 <div class="refsect1" lang="en">
 101 <a name="id2543429"></a><h2>DESCRIPTION</h2>
 102 <p>
 103       These functions perform thread safe, protocol independent
 104       nodename-to-address and address-to-nodename
 105       translation as defined in RFC2553.
 106     </p>
 107 <p>
 108       They use a
 109       <span class="type">struct hostent</span>
 110       which is defined in
 111       <code class="filename">namedb.h</code>:
 112     </p>
 113 <pre class="programlisting">
 114 struct  hostent {
 115         char    *h_name;        /* official name of host */
 116         char    **h_aliases;    /* alias list */
 117         int     h_addrtype;     /* host address type */
 118         int     h_length;       /* length of address */
 119         char    **h_addr_list;  /* list of addresses from name server */
 120 };
 121 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
 122 </pre>
 123 <p>
 124     </p>
 125 <p>
 126       The members of this structure are:
 127       </p>
 128 <div class="variablelist"><dl>
 129 <dt><span class="term"><code class="constant">h_name</code></span></dt>
 130 <dd><p>
 131               The official (canonical) name of the host.
 132             </p></dd>
 133 <dt><span class="term"><code class="constant">h_aliases</code></span></dt>
 134 <dd><p>
 135               A NULL-terminated array of alternate names (nicknames) for the
 136               host.
 137             </p></dd>
 138 <dt><span class="term"><code class="constant">h_addrtype</code></span></dt>
 139 <dd><p>
 140               The type of address being returned - usually
 141               <span class="type">PF_INET</span>
 142               or
 143               <span class="type">PF_INET6</span>.
 144
 145             </p></dd>
 146 <dt><span class="term"><code class="constant">h_length</code></span></dt>
 147 <dd><p>
 148               The length of the address in bytes.
 149             </p></dd>
 150 <dt><span class="term"><code class="constant">h_addr_list</code></span></dt>
 151 <dd><p>
 152               A
 153               <span class="type">NULL</span>
 154               terminated array of network addresses for the host.
 155               Host addresses are returned in network byte order.
 156             </p></dd>
 157 </dl></div>
 158 <p>
 159     </p>
 160 <p><code class="function">lwres_getipnodebyname()</code>
 161       looks up addresses of protocol family <em class="parameter"><code>af</code></em>
 162       for the hostname <em class="parameter"><code>name</code></em>.  The
 163       <em class="parameter"><code>flags</code></em> parameter contains ORed flag bits
 164       to specify the types of addresses that are searched for, and the
 165       types of addresses that are returned.  The flag bits are:
 166
 167       </p>
 168 <div class="variablelist"><dl>
 169 <dt><span class="term"><code class="constant">AI_V4MAPPED</code></span></dt>
 170 <dd><p>
 171               This is used with an
 172               <em class="parameter"><code>af</code></em>
 173               of AF_INET6, and causes IPv4 addresses to be returned as
 174               IPv4-mapped
 175               IPv6 addresses.
 176             </p></dd>
 177 <dt><span class="term"><code class="constant">AI_ALL</code></span></dt>
 178 <dd><p>
 179               This is used with an
 180               <em class="parameter"><code>af</code></em>
 181               of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
 182               be returned.
 183               If AI_V4MAPPED is also set, the IPv4 addresses are return as
 184               mapped
 185               IPv6 addresses.
 186             </p></dd>
 187 <dt><span class="term"><code class="constant">AI_ADDRCONFIG</code></span></dt>
 188 <dd><p>
 189               Only return an IPv6 or IPv4 address if here is an active network
 190               interface of that type.  This is not currently implemented
 191               in the BIND 9 lightweight resolver, and the flag is ignored.
 192             </p></dd>
 193 <dt><span class="term"><code class="constant">AI_DEFAULT</code></span></dt>
 194 <dd><p>
 195               This default sets the
 196               <code class="constant">AI_V4MAPPED</code>
 197               and
 198               <code class="constant">AI_ADDRCONFIG</code>
 199               flag bits.
 200             </p></dd>
 201 </dl></div>
 202 <p>
 203     </p>
 204 <p><code class="function">lwres_getipnodebyaddr()</code>
 205       performs a reverse lookup of address <em class="parameter"><code>src</code></em>
 206       which is <em class="parameter"><code>len</code></em> bytes long.
 207       <em class="parameter"><code>af</code></em> denotes the protocol family, typically
 208       <span class="type">PF_INET</span> or <span class="type">PF_INET6</span>.
 209     </p>
 210 <p><code class="function">lwres_freehostent()</code>
 211       releases all the memory associated with the <span class="type">struct
 212       hostent</span> pointer <em class="parameter"><code>he</code></em>.  Any memory
 213       allocated for the <code class="constant">h_name</code>,
 214       <code class="constant">h_addr_list</code> and
 215       <code class="constant">h_aliases</code> is freed, as is the memory for
 216       the <span class="type">hostent</span> structure itself.
 217     </p>
 218 </div>
 219 <div class="refsect1" lang="en">
 220 <a name="id2543687"></a><h2>RETURN VALUES</h2>
 221 <p>
 222       If an error occurs,
 223       <code class="function">lwres_getipnodebyname()</code>
 224       and
 225       <code class="function">lwres_getipnodebyaddr()</code>
 226       set
 227       <em class="parameter"><code>*error_num</code></em>
 228       to an appropriate error code and the function returns a
 229       <span class="type">NULL</span>
 230       pointer.
 231       The error codes and their meanings are defined in
 232       <code class="filename">&lt;lwres/netdb.h&gt;</code>:
 233       </p>
 234 <div class="variablelist"><dl>
 235 <dt><span class="term"><code class="constant">HOST_NOT_FOUND</code></span></dt>
 236 <dd><p>
 237               No such host is known.
 238             </p></dd>
 239 <dt><span class="term"><code class="constant">NO_ADDRESS</code></span></dt>
 240 <dd><p>
 241               The server recognised the request and the name but no address is
 242               available.  Another type of request to the name server for the
 243               domain might return an answer.
 244             </p></dd>
 245 <dt><span class="term"><code class="constant">TRY_AGAIN</code></span></dt>
 246 <dd><p>
 247               A temporary and possibly transient error occurred, such as a
 248               failure of a server to respond.  The request may succeed if
 249               retried.
 250             </p></dd>
 251 <dt><span class="term"><code class="constant">NO_RECOVERY</code></span></dt>
 252 <dd><p>
 253               An unexpected failure occurred, and retrying the request
 254               is pointless.
 255             </p></dd>
 256 </dl></div>
 257 <p>
 258     </p>
 259 <p><span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>
 260       translates these error codes to suitable error messages.
 261     </p>
 262 </div>
 263 <div class="refsect1" lang="en">
 264 <a name="id2543784"></a><h2>SEE ALSO</h2>
 265 <p><span class="citerefentry"><span class="refentrytitle">RFC2553</span></span>,
 266
 267       <span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>,
 268
 269       <span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>,
 270
 271       <span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>,
 272
 273       <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>,
 274
 275       <span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>.
 276     </p>
 277 </div>
 278 </div></body>
 279 </html>