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

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