summaryrefslogtreecommitdiffstats
path: root/lib/lwres/man/lwres_getipnode.docbook
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--lib/lwres/man/lwres_getipnode.docbook323
1 files changed, 323 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_getipnode.docbook b/lib/lwres/man/lwres_getipnode.docbook
new file mode 100644
index 0000000..d9c92f0
--- /dev/null
+++ b/lib/lwres/man/lwres_getipnode.docbook
@@ -0,0 +1,323 @@
+<!--
+ - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ -
+ - See the COPYRIGHT file distributed with this work for additional
+ - information regarding copyright ownership.
+-->
+
+<!-- Converted by db4-upgrade version 1.0 -->
+<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">
+ <info>
+ <date>2007-06-18</date>
+ </info>
+ <refentryinfo>
+ <corpname>ISC</corpname>
+ <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>lwres_getipnode</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo>BIND9</refmiscinfo>
+ </refmeta>
+
+ <docinfo>
+ <copyright>
+ <year>2000</year>
+ <year>2001</year>
+ <year>2003</year>
+ <year>2004</year>
+ <year>2005</year>
+ <year>2007</year>
+ <year>2014</year>
+ <year>2015</year>
+ <year>2016</year>
+ <year>2018</year>
+ <year>2019</year>
+ <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
+ </copyright>
+ </docinfo>
+
+ <refnamediv>
+ <refname>lwres_getipnodebyname</refname>
+ <refname>lwres_getipnodebyaddr</refname>
+ <refname>lwres_freehostent</refname>
+ <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <funcsynopsis>
+<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
+<funcprototype>
+ <funcdef>
+struct hostent *
+<function>lwres_getipnodebyname</function></funcdef>
+ <paramdef>const char *<parameter>name</parameter></paramdef>
+ <paramdef>int <parameter>af</parameter></paramdef>
+ <paramdef>int <parameter>flags</parameter></paramdef>
+ <paramdef>int *<parameter>error_num</parameter></paramdef>
+ </funcprototype>
+<funcprototype>
+ <funcdef>
+struct hostent *
+<function>lwres_getipnodebyaddr</function></funcdef>
+ <paramdef>const void *<parameter>src</parameter></paramdef>
+ <paramdef>size_t <parameter>len</parameter></paramdef>
+ <paramdef>int <parameter>af</parameter></paramdef>
+ <paramdef>int *<parameter>error_num</parameter></paramdef>
+ </funcprototype>
+<funcprototype>
+ <funcdef>
+void
+<function>lwres_freehostent</function></funcdef>
+ <paramdef>struct hostent *<parameter>he</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection><info><title>DESCRIPTION</title></info>
+
+
+ <para>
+ These functions perform thread safe, protocol independent
+ nodename-to-address and address-to-nodename
+ translation as defined in RFC2553.
+ </para>
+
+ <para>
+ They use a
+ <type>struct hostent</type>
+ which is defined in
+ <filename>namedb.h</filename>:
+ </para>
+ <para><programlisting>
+struct hostent {
+ char *h_name; /* official name of host */
+ char **h_aliases; /* alias list */
+ int h_addrtype; /* host address type */
+ int h_length; /* length of address */
+ char **h_addr_list; /* list of addresses from name server */
+};
+#define h_addr h_addr_list[0] /* address, for backward compatibility */
+</programlisting>
+ </para>
+
+ <para>
+ The members of this structure are:
+ <variablelist>
+ <varlistentry>
+ <term><constant>h_name</constant></term>
+ <listitem>
+ <para>
+ The official (canonical) name of the host.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>h_aliases</constant></term>
+ <listitem>
+ <para>
+ A NULL-terminated array of alternate names (nicknames) for the
+ host.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>h_addrtype</constant></term>
+ <listitem>
+ <para>
+ The type of address being returned - usually
+ <type>PF_INET</type>
+ or
+ <type>PF_INET6</type>.
+
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>h_length</constant></term>
+ <listitem>
+ <para>
+ The length of the address in bytes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>h_addr_list</constant></term>
+ <listitem>
+ <para>
+ A
+ <type>NULL</type>
+ terminated array of network addresses for the host.
+ Host addresses are returned in network byte order.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para><function>lwres_getipnodebyname()</function>
+ looks up addresses of protocol family <parameter>af</parameter>
+ for the hostname <parameter>name</parameter>. The
+ <parameter>flags</parameter> parameter contains ORed flag bits
+ to specify the types of addresses that are searched for, and the
+ types of addresses that are returned. The flag bits are:
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>AI_V4MAPPED</constant></term>
+ <listitem>
+ <para>
+ This is used with an
+ <parameter>af</parameter>
+ of AF_INET6, and causes IPv4 addresses to be returned as
+ IPv4-mapped
+ IPv6 addresses.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>AI_ALL</constant></term>
+ <listitem>
+ <para>
+ This is used with an
+ <parameter>af</parameter>
+ of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
+ be returned.
+ If AI_V4MAPPED is also set, the IPv4 addresses are return as
+ mapped
+ IPv6 addresses.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>AI_ADDRCONFIG</constant></term>
+ <listitem>
+ <para>
+ Only return an IPv6 or IPv4 address if here is an active network
+ interface of that type. This is not currently implemented
+ in the BIND 9 lightweight resolver, and the flag is ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>AI_DEFAULT</constant></term>
+ <listitem>
+ <para>
+ This default sets the
+ <constant>AI_V4MAPPED</constant>
+ and
+ <constant>AI_ADDRCONFIG</constant>
+ flag bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para><function>lwres_getipnodebyaddr()</function>
+ performs a reverse lookup of address <parameter>src</parameter>
+ which is <parameter>len</parameter> bytes long.
+ <parameter>af</parameter> denotes the protocol family, typically
+ <type>PF_INET</type> or <type>PF_INET6</type>.
+ </para>
+ <para><function>lwres_freehostent()</function>
+ releases all the memory associated with the <type>struct
+ hostent</type> pointer <parameter>he</parameter>. Any memory
+ allocated for the <constant>h_name</constant>,
+ <constant>h_addr_list</constant> and
+ <constant>h_aliases</constant> is freed, as is the memory for
+ the <type>hostent</type> structure itself.
+ </para>
+ </refsection>
+ <refsection><info><title>RETURN VALUES</title></info>
+
+ <para>
+ If an error occurs,
+ <function>lwres_getipnodebyname()</function>
+ and
+ <function>lwres_getipnodebyaddr()</function>
+ set
+ <parameter>*error_num</parameter>
+ to an appropriate error code and the function returns a
+ <type>NULL</type>
+ pointer.
+ The error codes and their meanings are defined in
+ <filename>&lt;lwres/netdb.h&gt;</filename>:
+ <variablelist>
+ <varlistentry>
+ <term><constant>HOST_NOT_FOUND</constant></term>
+ <listitem>
+ <para>
+ No such host is known.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>NO_ADDRESS</constant></term>
+ <listitem>
+ <para>
+ The server recognised the request and the name but no address is
+ available. Another type of request to the name server for the
+ domain might return an answer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>TRY_AGAIN</constant></term>
+ <listitem>
+ <para>
+ A temporary and possibly transient error occurred, such as a
+ failure of a server to respond. The request may succeed if
+ retried.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>NO_RECOVERY</constant></term>
+ <listitem>
+ <para>
+ An unexpected failure occurred, and retrying the request
+ is pointless.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para><citerefentry>
+ <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ translates these error codes to suitable error messages.
+ </para>
+ </refsection>
+ <refsection><info><title>SEE ALSO</title></info>
+
+ <para><citerefentry>
+ <refentrytitle>RFC2553</refentrytitle>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ </para>
+ </refsection>
+</refentry>