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

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