/contrib/bind9/lib/lwres/man/lwres_gethostent.docbook
Unknown | 440 lines | 421 code | 19 blank | 0 comment | 0 complexity | d9ca5281274ce12580503065d9704e59 MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 3 [<!ENTITY mdash "—">]> 4<!-- 5 - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC") 6 - Copyright (C) 2001 Internet Software Consortium. 7 - 8 - Permission to use, copy, modify, and/or distribute this software for any 9 - purpose with or without fee is hereby granted, provided that the above 10 - copyright notice and this permission notice appear in all copies. 11 - 12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 18 - PERFORMANCE OF THIS SOFTWARE. 19--> 20 21<!-- $Id$ --> 22<refentry> 23 24 <refentryinfo> 25 <date>Jun 30, 2000</date> 26 </refentryinfo> 27 28 <refmeta> 29 <refentrytitle>lwres_gethostent</refentrytitle> 30 <manvolnum>3</manvolnum> 31 <refmiscinfo>BIND9</refmiscinfo> 32 </refmeta> 33 34 <docinfo> 35 <copyright> 36 <year>2004</year> 37 <year>2005</year> 38 <year>2007</year> 39 <year>2012</year> 40 <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 41 </copyright> 42 <copyright> 43 <year>2001</year> 44 <holder>Internet Software Consortium.</holder> 45 </copyright> 46 </docinfo> 47 48 <refnamediv> 49 <refname>lwres_gethostbyname</refname> 50 <refname>lwres_gethostbyname2</refname> 51 <refname>lwres_gethostbyaddr</refname> 52 <refname>lwres_gethostent</refname> 53 <refname>lwres_sethostent</refname> 54 <refname>lwres_endhostent</refname> 55 <refname>lwres_gethostbyname_r</refname> 56 <refname>lwres_gethostbyaddr_r</refname> 57 <refname>lwres_gethostent_r</refname> 58 <refname>lwres_sethostent_r</refname> 59 <refname>lwres_endhostent_r</refname> 60 <refpurpose>lightweight resolver get network host entry</refpurpose> 61 </refnamediv> 62 <refsynopsisdiv> 63 <funcsynopsis> 64<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> 65<funcprototype> 66 <funcdef> 67struct hostent * 68<function>lwres_gethostbyname</function></funcdef> 69 <paramdef>const char *<parameter>name</parameter></paramdef> 70 </funcprototype> 71<funcprototype> 72 <funcdef> 73struct hostent * 74<function>lwres_gethostbyname2</function></funcdef> 75 <paramdef>const char *<parameter>name</parameter></paramdef> 76 <paramdef>int <parameter>af</parameter></paramdef> 77 </funcprototype> 78<funcprototype> 79 <funcdef> 80struct hostent * 81<function>lwres_gethostbyaddr</function></funcdef> 82 <paramdef>const char *<parameter>addr</parameter></paramdef> 83 <paramdef>int <parameter>len</parameter></paramdef> 84 <paramdef>int <parameter>type</parameter></paramdef> 85 </funcprototype> 86<funcprototype> 87 <funcdef> 88struct hostent * 89<function>lwres_gethostent</function></funcdef> 90 <paramdef>void</paramdef> 91 </funcprototype> 92<funcprototype> 93 <funcdef> 94void 95<function>lwres_sethostent</function></funcdef> 96 <paramdef>int <parameter>stayopen</parameter></paramdef> 97 </funcprototype> 98<funcprototype> 99 <funcdef> 100void 101<function>lwres_endhostent</function></funcdef> 102 <paramdef>void</paramdef> 103 </funcprototype> 104<funcprototype> 105 <funcdef> 106struct hostent * 107<function>lwres_gethostbyname_r</function></funcdef> 108 <paramdef>const char *<parameter>name</parameter></paramdef> 109 <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef> 110 <paramdef>char *<parameter>buf</parameter></paramdef> 111 <paramdef>int <parameter>buflen</parameter></paramdef> 112 <paramdef>int *<parameter>error</parameter></paramdef> 113 </funcprototype> 114<funcprototype> 115 <funcdef> 116struct hostent * 117<function>lwres_gethostbyaddr_r</function></funcdef> 118 <paramdef>const char *<parameter>addr</parameter></paramdef> 119 <paramdef>int <parameter>len</parameter></paramdef> 120 <paramdef>int <parameter>type</parameter></paramdef> 121 <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef> 122 <paramdef>char *<parameter>buf</parameter></paramdef> 123 <paramdef>int <parameter>buflen</parameter></paramdef> 124 <paramdef>int *<parameter>error</parameter></paramdef> 125 </funcprototype> 126<funcprototype> 127 <funcdef> 128struct hostent * 129<function>lwres_gethostent_r</function></funcdef> 130 <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef> 131 <paramdef>char *<parameter>buf</parameter></paramdef> 132 <paramdef>int <parameter>buflen</parameter></paramdef> 133 <paramdef>int *<parameter>error</parameter></paramdef> 134 </funcprototype> 135<funcprototype> 136 <funcdef> 137void 138<function>lwres_sethostent_r</function></funcdef> 139 <paramdef>int <parameter>stayopen</parameter></paramdef> 140 </funcprototype> 141<funcprototype> 142 <funcdef> 143void 144<function>lwres_endhostent_r</function></funcdef> 145 <paramdef>void</paramdef> 146 </funcprototype> 147</funcsynopsis> 148 </refsynopsisdiv> 149 150 <refsect1> 151 <title>DESCRIPTION</title> 152 <para> 153 These functions provide hostname-to-address and 154 address-to-hostname lookups by means of the lightweight resolver. 155 They are similar to the standard 156 <citerefentry> 157 <refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum> 158 </citerefentry> 159 functions provided by most operating systems. 160 They use a 161 <type>struct hostent</type> 162 which is usually defined in 163 <filename><namedb.h></filename>. 164 </para> 165 <para><programlisting> 166struct hostent { 167 char *h_name; /* official name of host */ 168 char **h_aliases; /* alias list */ 169 int h_addrtype; /* host address type */ 170 int h_length; /* length of address */ 171 char **h_addr_list; /* list of addresses from name server */ 172}; 173#define h_addr h_addr_list[0] /* address, for backward compatibility */ 174</programlisting> 175 </para> 176 <para> 177 The members of this structure are: 178 <variablelist> 179 <varlistentry> 180 <term><constant>h_name</constant></term> 181 <listitem> 182 <para> 183 The official (canonical) name of the host. 184 </para> 185 </listitem> 186 </varlistentry> 187 <varlistentry> 188 <term><constant>h_aliases</constant></term> 189 <listitem> 190 <para> 191 A NULL-terminated array of alternate names (nicknames) for the 192 host. 193 </para> 194 </listitem> 195 </varlistentry> 196 <varlistentry> 197 <term><constant>h_addrtype</constant></term> 198 <listitem> 199 <para> 200 The type of address being returned — 201 <type>PF_INET</type> 202 or 203 <type>PF_INET6</type>. 204 </para> 205 </listitem> 206 </varlistentry> 207 <varlistentry> 208 <term><constant>h_length</constant></term> 209 <listitem> 210 <para> 211 The length of the address in bytes. 212 </para> 213 </listitem> 214 </varlistentry> 215 <varlistentry> 216 <term><constant>h_addr_list</constant></term> 217 <listitem> 218 <para> 219 A <type>NULL</type> 220 terminated array of network addresses for the host. 221 Host addresses are returned in network byte order. 222 </para> 223 </listitem> 224 </varlistentry> 225 </variablelist> 226 </para> 227 <para> 228 For backward compatibility with very old software, 229 <constant>h_addr</constant> 230 is the first address in 231 <constant>h_addr_list.</constant> 232 </para> 233 <para><function>lwres_gethostent()</function>, 234 <function>lwres_sethostent()</function>, 235 <function>lwres_endhostent()</function>, 236 <function>lwres_gethostent_r()</function>, 237 <function>lwres_sethostent_r()</function> 238 and 239 <function>lwres_endhostent_r()</function> 240 provide iteration over the known host entries on systems that 241 provide such functionality through facilities like 242 <filename>/etc/hosts</filename> 243 or NIS. The lightweight resolver does not currently implement 244 these functions; it only provides them as stub functions that always 245 return failure. 246 </para> 247 248 <para><function>lwres_gethostbyname()</function> 249 and <function>lwres_gethostbyname2()</function> look up the 250 hostname <parameter>name</parameter>. 251 <function>lwres_gethostbyname()</function> always looks for an 252 IPv4 address while <function>lwres_gethostbyname2()</function> 253 looks for an address of protocol family 254 <parameter>af</parameter>: either <type>PF_INET</type> or 255 <type>PF_INET6</type> — IPv4 or IPV6 addresses 256 respectively. Successful calls of the functions return a 257 <type>struct hostent</type>for the name that was looked up. 258 <type>NULL</type> is returned if the lookups by 259 <function>lwres_gethostbyname()</function> or 260 <function>lwres_gethostbyname2()</function> fail. 261 </para> 262 263 <para> 264 Reverse lookups of addresses are performed by 265 <function>lwres_gethostbyaddr()</function>. 266 <parameter>addr</parameter> is an address of length 267 <parameter>len</parameter> bytes and protocol family 268 <parameter>type</parameter> — <type>PF_INET</type> or 269 <type>PF_INET6</type>. 270 <function>lwres_gethostbyname_r()</function> is a 271 thread-safe function 272 for forward lookups. If an error occurs, an error code is returned in 273 <parameter>*error</parameter>. 274 <parameter>resbuf</parameter> is a pointer to a 275 <type>struct hostent</type> which is initialised by a successful call to 276 <function>lwres_gethostbyname_r()</function>. 277 <parameter>buf</parameter> is a buffer of length 278 <parameter>len</parameter> bytes which is used to store the 279 <constant>h_name</constant>, <constant>h_aliases</constant>, and 280 <constant>h_addr_list</constant> elements of the 281 <type>struct hostent</type> returned in <parameter>resbuf</parameter>. 282 Successful calls to <function>lwres_gethostbyname_r()</function> 283 return <parameter>resbuf</parameter>, 284 which is a pointer to the <type>struct hostent</type> it created. 285 </para> 286 287 <para><function>lwres_gethostbyaddr_r()</function> 288 is a thread-safe function 289 that performs a reverse lookup of address <parameter>addr</parameter> 290 which is <parameter>len</parameter> bytes long and is of 291 protocol 292 family <parameter>type</parameter> — <type>PF_INET</type> or 293 <type>PF_INET6</type>. If an error occurs, the error code is returned 294 in <parameter>*error</parameter>. The other function 295 parameters are 296 identical to those in <function>lwres_gethostbyname_r()</function>. 297 <parameter>resbuf</parameter> is a pointer to a 298 <type>struct hostent</type> which is initialised by a successful call to 299 <function>lwres_gethostbyaddr_r()</function>. 300 <parameter>buf</parameter> is a buffer of length 301 <parameter>len</parameter> bytes which is used to store the 302 <constant>h_name</constant>, <constant>h_aliases</constant>, and 303 <constant>h_addr_list</constant> elements of the 304 <type>struct hostent</type> returned in <parameter>resbuf</parameter>. 305 Successful calls to <function>lwres_gethostbyaddr_r()</function> return 306 <parameter>resbuf</parameter>, which is a pointer to the 307 <function>struct hostent()</function> it created. 308 </para> 309 310 </refsect1> 311 312 <refsect1> 313 <title>RETURN VALUES</title> 314 <para> 315 The functions 316 <function>lwres_gethostbyname()</function>, 317 <function>lwres_gethostbyname2()</function>, 318 <function>lwres_gethostbyaddr()</function>, 319 and 320 <function>lwres_gethostent()</function> 321 return NULL to indicate an error. In this case the global variable 322 <type>lwres_h_errno</type> 323 will contain one of the following error codes defined in 324 <filename><lwres/netdb.h></filename>: 325 326 <variablelist> 327 <varlistentry> 328 <term><constant>HOST_NOT_FOUND</constant></term> 329 <listitem> 330 <para> 331 The host or address was not found. 332 </para> 333 </listitem> 334 </varlistentry> 335 <varlistentry> 336 <term><constant>TRY_AGAIN</constant></term> 337 <listitem> 338 <para> 339 A recoverable error occurred, e.g., a timeout. 340 Retrying the lookup may succeed. 341 </para> 342 </listitem> 343 </varlistentry> 344 <varlistentry> 345 <term><constant>NO_RECOVERY</constant></term> 346 <listitem> 347 <para> 348 A non-recoverable error occurred. 349 </para> 350 </listitem> 351 </varlistentry> 352 <varlistentry> 353 <term><constant>NO_DATA</constant></term> 354 <listitem> 355 <para> 356 The name exists, but has no address information 357 associated with it (or vice versa in the case 358 of a reverse lookup). The code NO_ADDRESS 359 is accepted as a synonym for NO_DATA for backwards 360 compatibility. 361 </para> 362 </listitem> 363 </varlistentry> 364 </variablelist> 365 </para> 366 367 <para><citerefentry> 368 <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> 369 </citerefentry> 370 translates these error codes to suitable error messages. 371 </para> 372 373 <para><function>lwres_gethostent()</function> 374 and <function>lwres_gethostent_r()</function> 375 always return <type>NULL</type>. 376 </para> 377 378 <para> 379 Successful calls to <function>lwres_gethostbyname_r()</function> and 380 <function>lwres_gethostbyaddr_r()</function> return 381 <parameter>resbuf</parameter>, a pointer to the 382 <type>struct hostent</type> that was initialised by these functions. They return 383 <type>NULL</type> if the lookups fail or if <parameter>buf</parameter> 384 was too small to hold the list of addresses and names referenced by 385 the <constant>h_name</constant>, <constant>h_aliases</constant>, and 386 <constant>h_addr_list</constant> elements of the 387 <type>struct hostent</type>. 388 If <parameter>buf</parameter> was too small, both 389 <function>lwres_gethostbyname_r()</function> and 390 <function>lwres_gethostbyaddr_r()</function> set the global 391 variable 392 <type>errno</type> to <errorcode>ERANGE</errorcode>. 393 </para> 394 395 </refsect1> 396 <refsect1> 397 <title>SEE ALSO</title> 398 <para><citerefentry> 399 <refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum> 400 </citerefentry>, 401 402 <citerefentry> 403 <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum> 404 </citerefentry>, 405 406 <citerefentry> 407 <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> 408 </citerefentry> 409 </para> 410 </refsect1> 411 412 <refsect1> 413 <title>BUGS</title> 414 <para><function>lwres_gethostbyname()</function>, 415 <function>lwres_gethostbyname2()</function>, 416 <function>lwres_gethostbyaddr()</function> 417 and 418 <function>lwres_endhostent()</function> 419 are not thread safe; they return pointers to static data and 420 provide error codes through a global variable. 421 Thread-safe versions for name and address lookup are provided by 422 <function>lwres_gethostbyname_r()</function>, 423 and 424 <function>lwres_gethostbyaddr_r()</function> 425 respectively. 426 </para> 427 <para> 428 The resolver daemon does not currently support any non-DNS 429 name services such as 430 <filename>/etc/hosts</filename> 431 or 432 <type>NIS</type>, 433 consequently the above functions don't, either. 434 </para> 435 </refsect1> 436</refentry><!-- 437 - Local variables: 438 - mode: sgml 439 - End: 440-->