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