1<!-- 2 - Copyright (C) 2004, 2005, 2007, 2014 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 --> 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 — 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 <lwres/netdb.h></pre> 34<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> 35<td><code class="funcdef"> 36struct 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"> 45struct 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"> 61struct 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"> 82struct 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"> 90void 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"> 98void 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"> 107struct 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"> 141struct 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"> 187struct 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"> 214void 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"> 222void 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="id2543618"></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"><namedb.h></code>. 242 </p> 243<pre class="programlisting"> 244struct 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 — 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> — 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> — <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> — <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="id2543969"></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"><lwres/netdb.h></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="id2544202"></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="id2544236"></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> 467