lwres_getipnode.docbook revision c651f15b30f1dae5cc2f00878fb5da5b3a35a468
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<!-- $Id: lwres_getipnode.docbook,v 1.7 2005/04/07 03:50:02 marka Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refentryinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_getipnode</refentrytitle>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refpurpose>lightweight resolver nodename / address translation API</refpurpose>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getipnodebyname</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getipnodebyaddr</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_freehostent</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese functions perform thread safe, protocol independent
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonnodename-to-address and address-to-nodename
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontranslation as defined in RFC2553.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhich is defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<programlisting>
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafssonstruct hostent {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char *h_name; /* official name of host */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char **h_aliases; /* alias list */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int h_addrtype; /* host address type */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int h_length; /* length of address */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char **h_addr_list; /* list of addresses from name server */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson#define h_addr h_addr_list[0] /* address, for backward compatibility */
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe members of this structure are:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>h_name</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe official (canonical) name of the host.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>h_aliases</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonA NULL-terminated array of alternate names (nicknames) for the host.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>h_addrtype</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe type of address being returned - usually
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>h_length</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe length of the address in bytes.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>h_addr_list</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonterminated array of network addresses for the host.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonHost addresses are returned in network byte order.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</variablelist>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getipnodebyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlooks up addresses of protocol family
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfor the hostname
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonparameter contains ORed flag bits to
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonspecify the types of addresses that are searched
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfor, and the types of addresses that are returned.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe flag bits are:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>AI_V4MAPPED</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis is used with an
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonof AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIPv6 addresses.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>AI_ALL</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis is used with an
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonof AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIf AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIPv6 addresses.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>AI_ADDRCONFIG</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonOnly return an IPv6 or IPv4 address if here is an active network
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoninterface of that type. This is not currently implemented
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonin the BIND 9 lightweight resolver, and the flag is ignored.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>AI_DEFAULT</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis default sets the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</variablelist>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getipnodebyaddr()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonperforms a reverse lookup
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssondenotes the protocol family, typically
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonreleases all the memory associated with
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonAny memory allocated for the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis freed, as is the memory for the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstructure itself.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIf an error occurs,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getipnodebyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getipnodebyaddr()</function>
b587e1d83f007ce68a9ae93097c461d8eb7aa373Mark Andrewsto an appropriate error code and the function returns a
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe error codes and their meanings are defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<filename><lwres/netdb.h></filename>:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonNo such host is known.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>NO_ADDRESS</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe server recognised the request and the name but no address is
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonavailable. Another type of request to the name server for the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssondomain might return an answer.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>TRY_AGAIN</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonA temporary and possibly transient error occurred, such as a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfailure of a server to respond. The request may succeed if
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>NO_RECOVERY</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonAn unexpected failure occurred, and retrying the request
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</variablelist>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontranslates these error codes to suitable error messages.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>.