lwres_getipnode.docbook revision 86b0285d7e65601645db4090d62ee6cb63abad6c
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - Copyright (C) 2001 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.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<!-- $Id: lwres_getipnode.docbook,v 1.4 2001/06/18 22:06:55 gson 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>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto an approriate 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>.