lwres_getipnode.docbook revision 938440694b33cd752e9e4b71a526368b4811c177
5cd4555ad444fd391002ae32450572054369fd42Rob Austein<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
5cd4555ad444fd391002ae32450572054369fd42Rob Austein "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein [<!ENTITY mdash "—">]>
938440694b33cd752e9e4b71a526368b4811c177Tinderbox User - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater - Permission to use, copy, modify, and/or 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.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getipnodebyname</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>const char *<parameter>name</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>int <parameter>af</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>int <parameter>flags</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>int *<parameter>error_num</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getipnodebyaddr</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>const void *<parameter>src</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>size_t <parameter>len</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>int <parameter>af</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>int *<parameter>error_num</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_freehostent</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>struct hostent *<parameter>he</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These functions perform thread safe, protocol independent
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein nodename-to-address and address-to-nodename
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein translation as defined in RFC2553.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein which is defined in
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>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The members of this structure are:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The official (canonical) name of the host.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein A NULL-terminated array of alternate names (nicknames) for the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The type of address being returned - usually
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The length of the address in bytes.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein terminated array of network addresses for the host.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Host addresses are returned in network byte order.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_getipnodebyname()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein looks up addresses of protocol family <parameter>af</parameter>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein for the hostname <parameter>name</parameter>. The
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>flags</parameter> parameter contains ORed flag bits
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to specify the types of addresses that are searched for, and the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein types of addresses that are returned. The flag bits are:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This is used with an
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein of AF_INET6, and causes IPv4 addresses to be returned as
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein IPv6 addresses.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This is used with an
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein be returned.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If AI_V4MAPPED is also set, the IPv4 addresses are return as
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein IPv6 addresses.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Only return an IPv6 or IPv4 address if here is an active network
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein interface of that type. This is not currently implemented
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in the BIND 9 lightweight resolver, and the flag is ignored.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This default sets the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_getipnodebyaddr()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein performs a reverse lookup of address <parameter>src</parameter>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>af</parameter> denotes the protocol family, typically
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein releases all the memory associated with the <type>struct
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein hostent</type> pointer <parameter>he</parameter>. Any memory
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <constant>h_aliases</constant> is freed, as is the memory for
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If an error occurs,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to an appropriate error code and the function returns a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The error codes and their meanings are defined in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term><constant>HOST_NOT_FOUND</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein No such host is known.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The server recognised the request and the name but no address is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein available. Another type of request to the name server for the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein domain might return an answer.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein A temporary and possibly transient error occurred, such as a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein failure of a server to respond. The request may succeed if
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein An unexpected failure occurred, and retrying the request
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is pointless.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein translates these error codes to suitable error messages.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - Local variables:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - mode: sgml