lwres_getipnode.docbook revision 14a656f94b1fd0ababd84a772228dfa52276ba15
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - Permission to use, copy, modify, and/or distribute this software for any
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - purpose with or without fee is hereby granted, provided that the above
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - copyright notice and this permission notice appear in all copies.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - PERFORMANCE OF THIS SOFTWARE.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington<!-- Converted by db4-upgrade version 1.0 -->
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refentryinfo>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </refentryinfo>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refentrytitle>lwres_getipnode</refentrytitle>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <holder>Internet Software Consortium.</holder>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </refnamediv>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refsynopsisdiv>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <funcsynopsis>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington<funcprototype>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellingtonstruct hostent *
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington<function>lwres_getipnodebyname</function></funcdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <paramdef>const char *<parameter>name</parameter></paramdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <paramdef>int <parameter>af</parameter></paramdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <paramdef>int <parameter>flags</parameter></paramdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <paramdef>int *<parameter>error_num</parameter></paramdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </funcprototype>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington<funcprototype>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellingtonstruct hostent *
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington<function>lwres_getipnodebyaddr</function></funcdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <paramdef>const void *<parameter>src</parameter></paramdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <paramdef>size_t <parameter>len</parameter></paramdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <paramdef>int <parameter>af</parameter></paramdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <paramdef>int *<parameter>error_num</parameter></paramdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </funcprototype>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington<funcprototype>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington<function>lwres_freehostent</function></funcdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <paramdef>struct hostent *<parameter>he</parameter></paramdef>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </funcprototype>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington</funcsynopsis>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </refsynopsisdiv>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refsection><info><title>DESCRIPTION</title></info>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington These functions perform thread safe, protocol independent
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington nodename-to-address and address-to-nodename
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington translation as defined in RFC2553.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington which is defined in
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellingtonstruct hostent {
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington char *h_name; /* official name of host */
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington char **h_aliases; /* alias list */
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington int h_addrtype; /* host address type */
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington int h_length; /* length of address */
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington char **h_addr_list; /* list of addresses from name server */
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington#define h_addr h_addr_list[0] /* address, for backward compatibility */
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington</programlisting>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington The members of this structure are:
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <variablelist>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington The official (canonical) name of the host.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <term><constant>h_aliases</constant></term>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington A NULL-terminated array of alternate names (nicknames) for the
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <term><constant>h_addrtype</constant></term>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington The type of address being returned - usually
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington The length of the address in bytes.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <term><constant>h_addr_list</constant></term>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington terminated array of network addresses for the host.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington Host addresses are returned in network byte order.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </variablelist>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <para><function>lwres_getipnodebyname()</function>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington looks up addresses of protocol family <parameter>af</parameter>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington for the hostname <parameter>name</parameter>. The
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <parameter>flags</parameter> parameter contains ORed flag bits
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington to specify the types of addresses that are searched for, and the
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington types of addresses that are returned. The flag bits are:
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <variablelist>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <term><constant>AI_V4MAPPED</constant></term>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington This is used with an
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington of AF_INET6, and causes IPv4 addresses to be returned as
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington IPv6 addresses.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington This is used with an
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington If AI_V4MAPPED is also set, the IPv4 addresses are return as
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington IPv6 addresses.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <term><constant>AI_ADDRCONFIG</constant></term>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington Only return an IPv6 or IPv4 address if here is an active network
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington interface of that type. This is not currently implemented
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington in the BIND 9 lightweight resolver, and the flag is ignored.
8ffa8320abcc17ae593af566cb946a58fe293860Brian Wellington </varlistentry>
8ffa8320abcc17ae593af566cb946a58fe293860Brian Wellington <varlistentry>
8ffa8320abcc17ae593af566cb946a58fe293860Brian Wellington <term><constant>AI_DEFAULT</constant></term>
8ffa8320abcc17ae593af566cb946a58fe293860Brian Wellington This default sets the
8ffa8320abcc17ae593af566cb946a58fe293860Brian Wellington </varlistentry>
8ffa8320abcc17ae593af566cb946a58fe293860Brian Wellington </variablelist>
8ffa8320abcc17ae593af566cb946a58fe293860Brian Wellington <para><function>lwres_getipnodebyaddr()</function>
8ffa8320abcc17ae593af566cb946a58fe293860Brian Wellington performs a reverse lookup of address <parameter>src</parameter>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington which is <parameter>len</parameter> bytes long.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <parameter>af</parameter> denotes the protocol family, typically
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <type>PF_INET</type> or <type>PF_INET6</type>.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <para><function>lwres_freehostent()</function>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington releases all the memory associated with the <type>struct
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington hostent</type> pointer <parameter>he</parameter>. Any memory
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington allocated for the <constant>h_name</constant>,
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <constant>h_aliases</constant> is freed, as is the memory for
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </refsection>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refsection><info><title>RETURN VALUES</title></info>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington If an error occurs,
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <function>lwres_getipnodebyname()</function>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <function>lwres_getipnodebyaddr()</function>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington to an appropriate error code and the function returns a
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington The error codes and their meanings are defined in
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <filename><lwres/netdb.h></filename>:
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <variablelist>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <term><constant>HOST_NOT_FOUND</constant></term>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington No such host is known.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <term><constant>NO_ADDRESS</constant></term>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington The server recognised the request and the name but no address is
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington available. Another type of request to the name server for the
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington domain might return an answer.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <term><constant>TRY_AGAIN</constant></term>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington A temporary and possibly transient error occurred, such as a
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington failure of a server to respond. The request may succeed if
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <term><constant>NO_RECOVERY</constant></term>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington An unexpected failure occurred, and retrying the request
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington is pointless.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </varlistentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </variablelist>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </citerefentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington translates these error codes to suitable error messages.
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </refsection>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refsection><info><title>SEE ALSO</title></info>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </citerefentry>,
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <citerefentry>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington </citerefentry>,