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