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

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2001 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_gethostent.html,v 1.24.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_gethostent</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_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent, lwres_sethostent, lwres_endhostent, lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r, lwres_sethostent_r, lwres_endhostent_r &#8212; lightweight resolver get network host entry</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"><tr>
  35 <td><code class="funcdef">
  36 struct hostent *
  37 <b class="fsfunc">lwres_gethostbyname</b>(</code></td>
  38 <td>const char * </td>
  39 <td>
  40 <var class="pdparam">name</var><code>)</code>;</td>
  41 </tr></table>
  42 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  43 <tr>
  44 <td><code class="funcdef">
  45 struct hostent *
  46 <b class="fsfunc">lwres_gethostbyname2</b>(</code></td>
  47 <td>const char * </td>
  48 <td>
  49 <var class="pdparam">name</var>, </td>
  50 </tr>
  51 <tr>
  52 <td> </td>
  53 <td>int  </td>
  54 <td>
  55 <var class="pdparam">af</var><code>)</code>;</td>
  56 </tr>
  57 </table>
  58 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  59 <tr>
  60 <td><code class="funcdef">
  61 struct hostent *
  62 <b class="fsfunc">lwres_gethostbyaddr</b>(</code></td>
  63 <td>const char * </td>
  64 <td>
  65 <var class="pdparam">addr</var>, </td>
  66 </tr>
  67 <tr>
  68 <td> </td>
  69 <td>int  </td>
  70 <td>
  71 <var class="pdparam">len</var>, </td>
  72 </tr>
  73 <tr>
  74 <td> </td>
  75 <td>int  </td>
  76 <td>
  77 <var class="pdparam">type</var><code>)</code>;</td>
  78 </tr>
  79 </table>
  80 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
  81 <td><code class="funcdef">
  82 struct hostent *
  83 <b class="fsfunc">lwres_gethostent</b>(</code></td>
  84 <td> </td>
  85 <td>
  86 <code>)</code>;</td>
  87 </tr></table>
  88 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
  89 <td><code class="funcdef">
  90 void
  91 <b class="fsfunc">lwres_sethostent</b>(</code></td>
  92 <td>int  </td>
  93 <td>
  94 <var class="pdparam">stayopen</var><code>)</code>;</td>
  95 </tr></table>
  96 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
  97 <td><code class="funcdef">
  98 void
  99 <b class="fsfunc">lwres_endhostent</b>(</code></td>
 100 <td> </td>
 101 <td>
 102 <code>)</code>;</td>
 103 </tr></table>
 104 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 105 <tr>
 106 <td><code class="funcdef">
 107 struct hostent *
 108 <b class="fsfunc">lwres_gethostbyname_r</b>(</code></td>
 109 <td>const char * </td>
 110 <td>
 111 <var class="pdparam">name</var>, </td>
 112 </tr>
 113 <tr>
 114 <td> </td>
 115 <td>struct hostent * </td>
 116 <td>
 117 <var class="pdparam">resbuf</var>, </td>
 118 </tr>
 119 <tr>
 120 <td> </td>
 121 <td>char * </td>
 122 <td>
 123 <var class="pdparam">buf</var>, </td>
 124 </tr>
 125 <tr>
 126 <td> </td>
 127 <td>int  </td>
 128 <td>
 129 <var class="pdparam">buflen</var>, </td>
 130 </tr>
 131 <tr>
 132 <td> </td>
 133 <td>int * </td>
 134 <td>
 135 <var class="pdparam">error</var><code>)</code>;</td>
 136 </tr>
 137 </table>
 138 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 139 <tr>
 140 <td><code class="funcdef">
 141 struct hostent  *
 142 <b class="fsfunc">lwres_gethostbyaddr_r</b>(</code></td>
 143 <td>const char * </td>
 144 <td>
 145 <var class="pdparam">addr</var>, </td>
 146 </tr>
 147 <tr>
 148 <td> </td>
 149 <td>int  </td>
 150 <td>
 151 <var class="pdparam">len</var>, </td>
 152 </tr>
 153 <tr>
 154 <td> </td>
 155 <td>int  </td>
 156 <td>
 157 <var class="pdparam">type</var>, </td>
 158 </tr>
 159 <tr>
 160 <td> </td>
 161 <td>struct hostent * </td>
 162 <td>
 163 <var class="pdparam">resbuf</var>, </td>
 164 </tr>
 165 <tr>
 166 <td> </td>
 167 <td>char * </td>
 168 <td>
 169 <var class="pdparam">buf</var>, </td>
 170 </tr>
 171 <tr>
 172 <td> </td>
 173 <td>int  </td>
 174 <td>
 175 <var class="pdparam">buflen</var>, </td>
 176 </tr>
 177 <tr>
 178 <td> </td>
 179 <td>int * </td>
 180 <td>
 181 <var class="pdparam">error</var><code>)</code>;</td>
 182 </tr>
 183 </table>
 184 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 185 <tr>
 186 <td><code class="funcdef">
 187 struct hostent  *
 188 <b class="fsfunc">lwres_gethostent_r</b>(</code></td>
 189 <td>struct hostent * </td>
 190 <td>
 191 <var class="pdparam">resbuf</var>, </td>
 192 </tr>
 193 <tr>
 194 <td> </td>
 195 <td>char * </td>
 196 <td>
 197 <var class="pdparam">buf</var>, </td>
 198 </tr>
 199 <tr>
 200 <td> </td>
 201 <td>int  </td>
 202 <td>
 203 <var class="pdparam">buflen</var>, </td>
 204 </tr>
 205 <tr>
 206 <td> </td>
 207 <td>int * </td>
 208 <td>
 209 <var class="pdparam">error</var><code>)</code>;</td>
 210 </tr>
 211 </table>
 212 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
 213 <td><code class="funcdef">
 214 void
 215 <b class="fsfunc">lwres_sethostent_r</b>(</code></td>
 216 <td>int  </td>
 217 <td>
 218 <var class="pdparam">stayopen</var><code>)</code>;</td>
 219 </tr></table>
 220 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr>
 221 <td><code class="funcdef">
 222 void
 223 <b class="fsfunc">lwres_endhostent_r</b>(</code></td>
 224 <td> </td>
 225 <td>
 226 <code>)</code>;</td>
 227 </tr></table>
 228 </div>
 229 </div>
 230 <div class="refsect1" lang="en">
 231 <a name="id2543606"></a><h2>DESCRIPTION</h2>
 232 <p>
 233       These functions provide hostname-to-address and
 234       address-to-hostname lookups by means of the lightweight resolver.
 235       They are similar to the standard
 236       <span class="citerefentry"><span class="refentrytitle">gethostent</span>(3)</span>
 237       functions provided by most operating systems.
 238       They use a
 239       <span class="type">struct hostent</span>
 240       which is usually defined in
 241       <code class="filename">&lt;namedb.h&gt;</code>.
 242     </p>
 243 <pre class="programlisting">
 244 struct  hostent {
 245         char    *h_name;        /* official name of host */
 246         char    **h_aliases;    /* alias list */
 247         int     h_addrtype;     /* host address type */
 248         int     h_length;       /* length of address */
 249         char    **h_addr_list;  /* list of addresses from name server */
 250 };
 251 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
 252 </pre>
 253 <p>
 254     </p>
 255 <p>
 256       The members of this structure are:
 257       </p>
 258 <div class="variablelist"><dl>
 259 <dt><span class="term"><code class="constant">h_name</code></span></dt>
 260 <dd><p>
 261               The official (canonical) name of the host.
 262             </p></dd>
 263 <dt><span class="term"><code class="constant">h_aliases</code></span></dt>
 264 <dd><p>
 265               A NULL-terminated array of alternate names (nicknames) for the
 266               host.
 267             </p></dd>
 268 <dt><span class="term"><code class="constant">h_addrtype</code></span></dt>
 269 <dd><p>
 270               The type of address being returned &#8212;
 271               <span class="type">PF_INET</span>
 272               or
 273               <span class="type">PF_INET6</span>.
 274             </p></dd>
 275 <dt><span class="term"><code class="constant">h_length</code></span></dt>
 276 <dd><p>
 277               The length of the address in bytes.
 278             </p></dd>
 279 <dt><span class="term"><code class="constant">h_addr_list</code></span></dt>
 280 <dd><p>
 281               A <span class="type">NULL</span>
 282               terminated array of network addresses for the host.
 283               Host addresses are returned in network byte order.
 284             </p></dd>
 285 </dl></div>
 286 <p>
 287     </p>
 288 <p>
 289       For backward compatibility with very old software,
 290       <code class="constant">h_addr</code>
 291       is the first address in
 292       <code class="constant">h_addr_list.</code>
 293     </p>
 294 <p><code class="function">lwres_gethostent()</code>,
 295       <code class="function">lwres_sethostent()</code>,
 296       <code class="function">lwres_endhostent()</code>,
 297       <code class="function">lwres_gethostent_r()</code>,
 298       <code class="function">lwres_sethostent_r()</code>
 299       and
 300       <code class="function">lwres_endhostent_r()</code>
 301       provide iteration over the known host entries on systems that
 302       provide such functionality through facilities like
 303       <code class="filename">/etc/hosts</code>
 304       or NIS.  The lightweight resolver does not currently implement
 305       these functions; it only provides them as stub functions that always
 306       return failure.
 307     </p>
 308 <p><code class="function">lwres_gethostbyname()</code>
 309       and <code class="function">lwres_gethostbyname2()</code> look up the
 310       hostname <em class="parameter"><code>name</code></em>.
 311       <code class="function">lwres_gethostbyname()</code> always looks for an
 312       IPv4 address while <code class="function">lwres_gethostbyname2()</code>
 313       looks for an address of protocol family
 314       <em class="parameter"><code>af</code></em>: either <span class="type">PF_INET</span> or
 315       <span class="type">PF_INET6</span> &#8212; IPv4 or IPV6 addresses
 316       respectively.  Successful calls of the functions return a
 317       <span class="type">struct hostent</span>for the name that was looked up.
 318       <span class="type">NULL</span> is returned if the lookups by
 319       <code class="function">lwres_gethostbyname()</code> or
 320       <code class="function">lwres_gethostbyname2()</code> fail.
 321     </p>
 322 <p>
 323       Reverse lookups of addresses are performed by
 324       <code class="function">lwres_gethostbyaddr()</code>.
 325       <em class="parameter"><code>addr</code></em> is an address of length
 326       <em class="parameter"><code>len</code></em> bytes and protocol family
 327       <em class="parameter"><code>type</code></em> &#8212; <span class="type">PF_INET</span> or
 328       <span class="type">PF_INET6</span>.
 329       <code class="function">lwres_gethostbyname_r()</code> is a
 330       thread-safe function
 331       for forward lookups.  If an error occurs, an error code is returned in
 332       <em class="parameter"><code>*error</code></em>.
 333       <em class="parameter"><code>resbuf</code></em> is a pointer to a
 334       <span class="type">struct hostent</span> which is initialised by a successful call to
 335       <code class="function">lwres_gethostbyname_r()</code>.
 336       <em class="parameter"><code>buf</code></em> is a buffer of length
 337       <em class="parameter"><code>len</code></em> bytes which is used to store the
 338       <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and
 339       <code class="constant">h_addr_list</code> elements of the
 340       <span class="type">struct hostent</span> returned in <em class="parameter"><code>resbuf</code></em>.
 341       Successful calls to <code class="function">lwres_gethostbyname_r()</code>
 342       return <em class="parameter"><code>resbuf</code></em>,
 343       which is a pointer to the <span class="type">struct hostent</span> it created.
 344     </p>
 345 <p><code class="function">lwres_gethostbyaddr_r()</code>
 346       is a thread-safe function
 347       that performs a reverse lookup of address <em class="parameter"><code>addr</code></em>
 348       which is <em class="parameter"><code>len</code></em> bytes long and is of
 349       protocol
 350       family <em class="parameter"><code>type</code></em> &#8212; <span class="type">PF_INET</span> or
 351       <span class="type">PF_INET6</span>.  If an error occurs, the error code is returned
 352       in <em class="parameter"><code>*error</code></em>.  The other function
 353       parameters are
 354       identical to those in <code class="function">lwres_gethostbyname_r()</code>.
 355       <em class="parameter"><code>resbuf</code></em> is a pointer to a
 356       <span class="type">struct hostent</span> which is initialised by a successful call to
 357       <code class="function">lwres_gethostbyaddr_r()</code>.
 358       <em class="parameter"><code>buf</code></em> is a buffer of length
 359       <em class="parameter"><code>len</code></em> bytes which is used to store the
 360       <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and
 361       <code class="constant">h_addr_list</code> elements of the
 362       <span class="type">struct hostent</span> returned in <em class="parameter"><code>resbuf</code></em>.
 363       Successful calls to <code class="function">lwres_gethostbyaddr_r()</code> return
 364       <em class="parameter"><code>resbuf</code></em>, which is a pointer to the
 365       <code class="function">struct hostent()</code> it created.
 366     </p>
 367 </div>
 368 <div class="refsect1" lang="en">
 369 <a name="id2543957"></a><h2>RETURN VALUES</h2>
 370 <p>
 371       The functions
 372       <code class="function">lwres_gethostbyname()</code>,
 373       <code class="function">lwres_gethostbyname2()</code>,
 374       <code class="function">lwres_gethostbyaddr()</code>,
 375       and
 376       <code class="function">lwres_gethostent()</code>
 377       return NULL to indicate an error.  In this case the global variable
 378       <span class="type">lwres_h_errno</span>
 379       will contain one of the following error codes defined in
 380       <code class="filename">&lt;lwres/netdb.h&gt;</code>:
 381
 382       </p>
 383 <div class="variablelist"><dl>
 384 <dt><span class="term"><code class="constant">HOST_NOT_FOUND</code></span></dt>
 385 <dd><p>
 386               The host or address was not found.
 387             </p></dd>
 388 <dt><span class="term"><code class="constant">TRY_AGAIN</code></span></dt>
 389 <dd><p>
 390               A recoverable error occurred, e.g., a timeout.
 391               Retrying the lookup may succeed.
 392             </p></dd>
 393 <dt><span class="term"><code class="constant">NO_RECOVERY</code></span></dt>
 394 <dd><p>
 395               A non-recoverable error occurred.
 396             </p></dd>
 397 <dt><span class="term"><code class="constant">NO_DATA</code></span></dt>
 398 <dd><p>
 399               The name exists, but has no address information
 400               associated with it (or vice versa in the case
 401               of a reverse lookup).  The code NO_ADDRESS
 402               is accepted as a synonym for NO_DATA for backwards
 403               compatibility.
 404             </p></dd>
 405 </dl></div>
 406 <p>
 407     </p>
 408 <p><span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>
 409       translates these error codes to suitable error messages.
 410     </p>
 411 <p><code class="function">lwres_gethostent()</code>
 412       and <code class="function">lwres_gethostent_r()</code>
 413       always return <span class="type">NULL</span>.
 414     </p>
 415 <p>
 416       Successful calls to <code class="function">lwres_gethostbyname_r()</code> and
 417       <code class="function">lwres_gethostbyaddr_r()</code> return
 418       <em class="parameter"><code>resbuf</code></em>, a pointer to the
 419       <span class="type">struct hostent</span> that was initialised by these functions.  They return
 420       <span class="type">NULL</span> if the lookups fail or if <em class="parameter"><code>buf</code></em>
 421       was too small to hold the list of addresses and names referenced by
 422       the <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and
 423       <code class="constant">h_addr_list</code> elements of the
 424       <span class="type">struct hostent</span>.
 425       If <em class="parameter"><code>buf</code></em> was too small, both
 426       <code class="function">lwres_gethostbyname_r()</code> and
 427       <code class="function">lwres_gethostbyaddr_r()</code> set the global
 428       variable
 429       <span class="type">errno</span> to <span class="errorcode">ERANGE</span>.
 430     </p>
 431 </div>
 432 <div class="refsect1" lang="en">
 433 <a name="id2544190"></a><h2>SEE ALSO</h2>
 434 <p><span class="citerefentry"><span class="refentrytitle">gethostent</span>(3)</span>,
 435
 436       <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>,
 437
 438       <span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>
 439     </p>
 440 </div>
 441 <div class="refsect1" lang="en">
 442 <a name="id2544225"></a><h2>BUGS</h2>
 443 <p><code class="function">lwres_gethostbyname()</code>,
 444       <code class="function">lwres_gethostbyname2()</code>,
 445       <code class="function">lwres_gethostbyaddr()</code>
 446       and
 447       <code class="function">lwres_endhostent()</code>
 448       are not thread safe; they return pointers to static data and
 449       provide error codes through a global variable.
 450       Thread-safe versions for name and address lookup are provided by
 451       <code class="function">lwres_gethostbyname_r()</code>,
 452       and
 453       <code class="function">lwres_gethostbyaddr_r()</code>
 454       respectively.
 455     </p>
 456 <p>
 457       The resolver daemon does not currently support any non-DNS
 458       name services such as
 459       <code class="filename">/etc/hosts</code>
 460       or
 461       <span class="type">NIS</span>,
 462       consequently the above functions don't, either.
 463     </p>
 464 </div>
 465 </div></body>
 466 </html>