lwres_getipnode.docbook revision d4ef65050feac78554addf6e16a06c6e2e0bd331
7cb128dc4cae2a03a742f63ba7afee23c78e3af0Phil Carmody<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen - Copyright (C) 2001 Internet Software Consortium.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen - Permission to use, copy, modify, and distribute this software for any
a85473f7c11c8734bdee9c2cbe4b767f144a18aaTimo Sirainen - purpose with or without fee is hereby granted, provided that the above
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen - copyright notice and this permission notice appear in all copies.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<!-- $Id: lwres_getipnode.docbook,v 1.2 2001/04/10 21:51:43 bwelling Exp $ -->
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<refentryinfo>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen</refentryinfo>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<refpurpose>lightweight resolver nodename / address translation API</refpurpose>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<refsynopsisdiv>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<funcsynopsis>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<funcprototype>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainenstruct hostent *
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<function>lwres_getipnodebyname</function></funcdef>
0219a05495ca78d0ccc2a4d5dcfcf17aa859481fTimo Sirainen</funcprototype>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<funcprototype>
0219a05495ca78d0ccc2a4d5dcfcf17aa859481fTimo Sirainenstruct hostent *
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<function>lwres_getipnodebyaddr</function></funcdef>
fd32c46c360e61de2c957c3d2241eaacab7b3eecTimo Sirainen</funcprototype>
fd32c46c360e61de2c957c3d2241eaacab7b3eecTimo Sirainen<funcprototype>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<function>lwres_freehostent</function></funcdef>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen</funcprototype>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen</funcsynopsis>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen</refsynopsisdiv>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenThese functions perform thread safe, protocol independent
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainennodename-to-address and address-to-nodename
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainentranslation as defined in RFC2553.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainenwhich is defined in
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<programlisting>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainenstruct hostent {
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen char *h_name; /* official name of host */
299451d50b891c83f4f5d921bc22715f24094236Timo Sirainen char **h_aliases; /* alias list */
299451d50b891c83f4f5d921bc22715f24094236Timo Sirainen int h_addrtype; /* host address type */
299451d50b891c83f4f5d921bc22715f24094236Timo Sirainen int h_length; /* length of address */
299451d50b891c83f4f5d921bc22715f24094236Timo Sirainen char **h_addr_list; /* list of addresses from name server */
299451d50b891c83f4f5d921bc22715f24094236Timo Sirainen#define h_addr h_addr_list[0] /* address, for backward compatibility */
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen</programlisting>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenThe members of this structure are:
a85473f7c11c8734bdee9c2cbe4b767f144a18aaTimo Sirainen<variablelist>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<varlistentry><term><constant>h_name</constant></term>
b8e6e314eb2f9f1fc8ce2999034321bfeb7a2269Timo SirainenThe official (canonical) name of the host.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<varlistentry><term><constant>h_aliases</constant></term>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenA NULL-terminated array of alternate names (nicknames) for the host.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<varlistentry><term><constant>h_addrtype</constant></term>
a85473f7c11c8734bdee9c2cbe4b767f144a18aaTimo SirainenThe type of address being returned - usually
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<varlistentry><term><constant>h_length</constant></term>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenThe length of the address in bytes.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<varlistentry><term><constant>h_addr_list</constant></term>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainenterminated array of network addresses for the host.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenHost addresses are returned in network byte order.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen</variablelist>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainenlooks up addresses of protocol family
e16052742970235960af359ce62515b9127c16fdTimo Sirainenfor the hostname
e16052742970235960af359ce62515b9127c16fdTimo Sirainenparameter contains ORed flag bits to
e16052742970235960af359ce62515b9127c16fdTimo Sirainenspecify the types of addresses that are searched
e16052742970235960af359ce62515b9127c16fdTimo Sirainenfor, and the types of addresses that are returned.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenThe flag bits are:
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<variablelist>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<varlistentry><term><constant>AI_V4MAPPED</constant></term>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenThis is used with an
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainenof AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenIPv6 addresses.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<varlistentry><term><constant>AI_ALL</constant></term>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenThis is used with an
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainenof AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenIf AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenIPv6 addresses.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<varlistentry><term><constant>AI_ADDRCONFIG</constant></term>
e9df0f285429d2b896ecdb4cd873d25e5e895620Timo SirainenOnly return an IPv6 or IPv4 address if here is an active network
e9df0f285429d2b896ecdb4cd873d25e5e895620Timo Siraineninterface of that type. This is not currently implemented
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainenin the BIND 9 lightweight resolver, and the flag is ignored.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<varlistentry><term><constant>AI_DEFAULT</constant></term>
e9df0f285429d2b896ecdb4cd873d25e5e895620Timo SirainenThis default sets the
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen</variablelist>
a46162e640e660638596a91032905ab9cb27bf04Timo Sirainenperforms a reverse lookup
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainendenotes the protocol family, typically
a46162e640e660638596a91032905ab9cb27bf04Timo Sirainenreleases all the memory associated with
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenAny memory allocated for the
e9df0f285429d2b896ecdb4cd873d25e5e895620Timo Sirainenis freed, as is the memory for the
a46162e640e660638596a91032905ab9cb27bf04Timo Sirainenstructure itself.
e9df0f285429d2b896ecdb4cd873d25e5e895620Timo SirainenIf an error occurs,
a46162e640e660638596a91032905ab9cb27bf04Timo Sirainento an approriate error code and the function returns a
e9df0f285429d2b896ecdb4cd873d25e5e895620Timo SirainenThe error codes and their meanings are defined in
a46162e640e660638596a91032905ab9cb27bf04Timo Sirainen<variablelist>
e9df0f285429d2b896ecdb4cd873d25e5e895620Timo Sirainen<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
e9df0f285429d2b896ecdb4cd873d25e5e895620Timo SirainenNo such host is known.
a46162e640e660638596a91032905ab9cb27bf04Timo Sirainen<varlistentry><term><constant>NO_ADDRESS</constant></term>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenThe server recognised the request and the name but no address is
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainenavailable. Another type of request to the name server for the
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainendomain might return an answer.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<varlistentry><term><constant>TRY_AGAIN</constant></term>
0219a05495ca78d0ccc2a4d5dcfcf17aa859481fTimo SirainenA temporary and possibly transient error occurred, such as a
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainenfailure of a server to respond. The request may succeed if
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<varlistentry><term><constant>NO_RECOVERY</constant></term>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo SirainenAn unexpected failure occurred, and retrying the request
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen</variablelist>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<citerefentry>
0219a05495ca78d0ccc2a4d5dcfcf17aa859481fTimo Sirainen<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen</citerefentry>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainentranslates these error codes to suitable error messages.
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<citerefentry>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen</citerefentry>,
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<citerefentry>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen</citerefentry>,
be2bc5677a16a3547d5cbfd21c9deedc96a759adTimo Sirainen<citerefentry>
be2bc5677a16a3547d5cbfd21c9deedc96a759adTimo Sirainen<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
be2bc5677a16a3547d5cbfd21c9deedc96a759adTimo Sirainen</citerefentry>,
36723cf206a7b64b9d972ab0719bbfaacc9316faTimo Sirainen<citerefentry>
36723cf206a7b64b9d972ab0719bbfaacc9316faTimo Sirainen<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
36723cf206a7b64b9d972ab0719bbfaacc9316faTimo Sirainen</citerefentry>,
e83126866761632b437e532dfdc30be01d14039dTimo Sirainen<citerefentry>
e83126866761632b437e532dfdc30be01d14039dTimo Sirainen<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
e83126866761632b437e532dfdc30be01d14039dTimo Sirainen</citerefentry>,
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<citerefentry>
7bd5b1c64cc987715bdaf8cc4907c3c37d5d7b29Timo Sirainen<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
e83126866761632b437e532dfdc30be01d14039dTimo Sirainen</citerefentry>.