lwres_getipnode.docbook revision d4ef65050feac78554addf6e16a06c6e2e0bd331
436aad11e01e916f75e68a2e9cb89ac217a990d3Tinderbox User<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
c7ef13f6c9ef4436bc804b150e0a93307b11fa27Tinderbox User - Copyright (C) 2001 Internet Software Consortium.
a5636b773fa05a272b6876afd99309c0b3090e2fMark Andrews - Permission to use, copy, modify, and distribute this software for any
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User - purpose with or without fee is hereby granted, provided that the above
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User - copyright notice and this permission notice appear in all copies.
5e047890ac9b745db060d95f7d1b4f876511240dTinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
137fdbc214e99c4cbe57551e9e14f2015c2e42aeTinderbox User - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
bed0874e1a09e810575328c4bfc346a47514b69fMark Andrews - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
02b47c5d62e1e827743684c28a08e871da454a2dMark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
e20309353e6246485c521278131d3fced73d7957Tinderbox User - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
9a5217f827ac0e006016745e5305b31dc0c7767fTinderbox User<!-- $Id: lwres_getipnode.docbook,v 1.2 2001/04/10 21:51:43 bwelling Exp $ -->
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<refentryinfo>
df4ebd8217d02dafc12145b55c4d93d0255d1ec7Tinderbox User</refentryinfo>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater<refentrytitle>lwres_getipnode</refentrytitle>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt<refpurpose>lightweight resolver nodename / address translation API</refpurpose>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<refsynopsisdiv>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt<funcsynopsis>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
24934f08b9ff81c2be711e566e8002d145573031Tinderbox User<funcprototype>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Huntstruct hostent *
24934f08b9ff81c2be711e566e8002d145573031Tinderbox User<function>lwres_getipnodebyname</function></funcdef>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater</funcprototype>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<funcprototype>
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updaterstruct hostent *
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<function>lwres_getipnodebyaddr</function></funcdef>
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews</funcprototype>
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews<funcprototype>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<function>lwres_freehostent</function></funcdef>
e20309353e6246485c521278131d3fced73d7957Tinderbox User</funcprototype>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews</funcsynopsis>
7feccf248d2a20a2ae48b290f58ded5abc853e9aTinderbox User</refsynopsisdiv>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsThese functions perform thread safe, protocol independent
ec7751119a08c6a7250f3187beed69a8b836d349Tinderbox Usernodename-to-address and address-to-nodename
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewstranslation as defined in RFC2553.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafssonwhich is defined in
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews<programlisting>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updaterstruct hostent {
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson char *h_name; /* official name of host */
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater char **h_aliases; /* alias list */
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater int h_addrtype; /* host address type */
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson int h_length; /* length of address */
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater char **h_addr_list; /* list of addresses from name server */
28a5dd720187fddb16055a0f64b63a7b66f29f64Mark Andrews#define h_addr h_addr_list[0] /* address, for backward compatibility */
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews</programlisting>
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark AndrewsThe members of this structure are:
28a5dd720187fddb16055a0f64b63a7b66f29f64Mark Andrews<variablelist>
28a5dd720187fddb16055a0f64b63a7b66f29f64Mark Andrews<varlistentry><term><constant>h_name</constant></term>
2a31bd531072824ef252c18303859d6af7451b00Francis DupontThe official (canonical) name of the host.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont<varlistentry><term><constant>h_aliases</constant></term>
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox UserA NULL-terminated array of alternate names (nicknames) for the host.
bed0874e1a09e810575328c4bfc346a47514b69fMark Andrews<varlistentry><term><constant>h_addrtype</constant></term>
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark AndrewsThe type of address being returned - usually
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<varlistentry><term><constant>h_length</constant></term>
b871c7156eb037d41f53828c6fcb9cc876128962Mark AndrewsThe length of the address in bytes.
b871c7156eb037d41f53828c6fcb9cc876128962Mark Andrews<varlistentry><term><constant>h_addr_list</constant></term>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updaterterminated array of network addresses for the host.
fa0326cc2cf428f67575b6ba3b97b528a31b0010Tinderbox UserHost addresses are returned in network byte order.
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater</variablelist>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater<function>lwres_getipnodebyname()</function>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafssonlooks up addresses of protocol family
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafssonfor the hostname
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updaterparameter contains ORed flag bits to
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updaterspecify the types of addresses that are searched
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updaterfor, and the types of addresses that are returned.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas GustafssonThe flag bits are:
5f7586ddbd3edd11272cdd30ed613d936129328bTinderbox User<varlistentry><term><constant>AI_V4MAPPED</constant></term>
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox UserThis is used with an
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox Userof AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
c7ef13f6c9ef4436bc804b150e0a93307b11fa27Tinderbox UserIPv6 addresses.
f132a836c4e386b1af045dd8fe7106ae61b90bffAutomatic Updater<varlistentry><term><constant>AI_ALL</constant></term>
609b8d08176469485edce25f3c2f50365bbd3819Mark AndrewsThis is used with an
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox Userof AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
8e5fce1f9ceba17dd7e3ff0eb287e1e999c14249Mark AndrewsIf AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
269519eeb959d905ed125f96426e01d725c3b597Tinderbox UserIPv6 addresses.
91d187ce035f39073f0732ff2a401a45c3c955fbMark Andrews<varlistentry><term><constant>AI_ADDRCONFIG</constant></term>
8e5fce1f9ceba17dd7e3ff0eb287e1e999c14249Mark AndrewsOnly return an IPv6 or IPv4 address if here is an active network
6a9d2121152c94cb9e35832126c3f2e4d18d81edTinderbox Userinterface of that type. This is not currently implemented
91d187ce035f39073f0732ff2a401a45c3c955fbMark Andrewsin the BIND 9 lightweight resolver, and the flag is ignored.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<varlistentry><term><constant>AI_DEFAULT</constant></term>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterThis default sets the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater</variablelist>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<function>lwres_getipnodebyaddr()</function>
7f94d9a8162c9a96b56e66176702b66e79d8e1a2Automatic Updaterperforms a reverse lookup
6a9d2121152c94cb9e35832126c3f2e4d18d81edTinderbox Userdenotes the protocol family, typically
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsreleases all the memory associated with
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsAny memory allocated for the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updateris freed, as is the memory for the
f751b1576ee6fef4023bf7101d10167e4fe520f3Tinderbox Userstructure itself.
dc5552b4df5e3821783821c8d4e734c1608c446eTinderbox UserIf an error occurs,
cf7e98f59148b559946a7f1ca728471374f1eef3Automatic Updater<function>lwres_getipnodebyname()</function>
cf7e98f59148b559946a7f1ca728471374f1eef3Automatic Updaterto an approriate error code and the function returns a
c3fd32ed29e9e419bb56583f4272a506773b1ea0Automatic UpdaterThe error codes and their meanings are defined in
fe600c3ad88c0bb078283a953d048087d227c0e5Tinderbox User<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
e20309353e6246485c521278131d3fced73d7957Tinderbox UserNo such host is known.
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User<varlistentry><term><constant>NO_ADDRESS</constant></term>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas GustafssonThe server recognised the request and the name but no address is
e2caa7536302de34de6cc04025abcd53dc3a499aAutomatic Updateravailable. Another type of request to the name server for the
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox Userdomain might return an answer.
0b57424d28c9a67018107133f9fbc0a7dcf057e2Mark Andrews<varlistentry><term><constant>TRY_AGAIN</constant></term>
e31cfd80616deb9781902306b34a69aa7309b6cbTinderbox UserA temporary and possibly transient error occurred, such as a
e31cfd80616deb9781902306b34a69aa7309b6cbTinderbox Userfailure of a server to respond. The request may succeed if
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews<varlistentry><term><constant>NO_RECOVERY</constant></term>
7d12a6b412fe47e6d6582923fd6954ab8cd0baebAutomatic UpdaterAn unexpected failure occurred, and retrying the request
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewsis pointless.
7d12a6b412fe47e6d6582923fd6954ab8cd0baebAutomatic Updater</variablelist>
0b57424d28c9a67018107133f9fbc0a7dcf057e2Mark Andrews<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updater</citerefentry>
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updatertranslates these error codes to suitable error messages.
b30ec46fec40a1b246f7965fbcd341fc6cfd1cc1Mark Andrews</citerefentry>,
82a986aaa5d3384a541b5a7d6dae8cf0726d6513Tinderbox User<citerefentry>
c7ef13f6c9ef4436bc804b150e0a93307b11fa27Tinderbox User<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews</citerefentry>,
dc435f1033bcba88b748074987db6cfd34c057a4Tinderbox User<citerefentry>
b30ec46fec40a1b246f7965fbcd341fc6cfd1cc1Mark Andrews<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
dc435f1033bcba88b748074987db6cfd34c057a4Tinderbox User</citerefentry>,
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User<citerefentry>
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater</citerefentry>,
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User<citerefentry>
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews</citerefentry>,
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<citerefentry>
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews</citerefentry>.