/contrib/bind9/lib/lwres/man/lwres_gethostent.docbook

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 440 lines · 421 code · 19 blank · 0 comment · 0 complexity · d9ca5281274ce12580503065d9704e59 MD5 · raw file

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