ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt [<!ENTITY mdash "&#8212;">]>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<refentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <refentryinfo>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <date>Jun 30, 2000</date>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </refentryinfo>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <refmeta>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <refentrytitle>lwres_getipnode</refentrytitle>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <manvolnum>3</manvolnum>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <refmiscinfo>BIND9</refmiscinfo>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </refmeta>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <docinfo>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <copyright>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <year>2004</year>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <year>2005</year>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <year>2007</year>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </copyright>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <copyright>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <year>2000</year>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <year>2001</year>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <year>2003</year>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <holder>Internet Software Consortium.</holder>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </copyright>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </docinfo>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <refnamediv>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <refname>lwres_getipnodebyname</refname>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <refname>lwres_getipnodebyaddr</refname>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <refname>lwres_freehostent</refname>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <refpurpose>lightweight resolver nodename / address translation API</refpurpose>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </refnamediv>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <refsynopsisdiv>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <funcsynopsis>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<funcprototype>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <funcdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntstruct hostent *

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<function>lwres_getipnodebyname</function></funcdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <paramdef>const char *<parameter>name</parameter></paramdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <paramdef>int <parameter>af</parameter></paramdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <paramdef>int <parameter>flags</parameter></paramdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <paramdef>int *<parameter>error_num</parameter></paramdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </funcprototype>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<funcprototype>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <funcdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntstruct hostent *

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<function>lwres_getipnodebyaddr</function></funcdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <paramdef>const void *<parameter>src</parameter></paramdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <paramdef>size_t <parameter>len</parameter></paramdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <paramdef>int <parameter>af</parameter></paramdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <paramdef>int *<parameter>error_num</parameter></paramdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </funcprototype>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<funcprototype>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <funcdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntvoid

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<function>lwres_freehostent</function></funcdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <paramdef>struct hostent *<parameter>he</parameter></paramdef>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </funcprototype>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt</funcsynopsis>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </refsynopsisdiv>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <refsect1>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <title>DESCRIPTION</title>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt These functions perform thread safe, protocol independent

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt nodename-to-address and address-to-nodename

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt translation as defined in RFC2553.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt They use a

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <type>struct hostent</type>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt which is defined in

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <filename>namedb.h</filename>:

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para><programlisting>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntstruct hostent {

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt char *h_name; /* official name of host */

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt char **h_aliases; /* alias list */

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt int h_addrtype; /* host address type */

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt int h_length; /* length of address */

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt char **h_addr_list; /* list of addresses from name server */

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt};

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt#define h_addr h_addr_list[0] /* address, for backward compatibility */

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt</programlisting>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt The members of this structure are:

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <variablelist>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <term><constant>h_name</constant></term>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt The official (canonical) name of the host.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <term><constant>h_aliases</constant></term>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt A NULL-terminated array of alternate names (nicknames) for the

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt host.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <term><constant>h_addrtype</constant></term>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt The type of address being returned - usually

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <type>PF_INET</type>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt or

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <type>PF_INET6</type>.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <term><constant>h_length</constant></term>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt The length of the address in bytes.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <term><constant>h_addr_list</constant></term>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt A

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <type>NULL</type>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt terminated array of network addresses for the host.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Host addresses are returned in network byte order.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </variablelist>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para><function>lwres_getipnodebyname()</function>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt looks up addresses of protocol family <parameter>af</parameter>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt for the hostname <parameter>name</parameter>. The

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <parameter>flags</parameter> parameter contains ORed flag bits

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt to specify the types of addresses that are searched for, and the

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt types of addresses that are returned. The flag bits are:

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <variablelist>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <term><constant>AI_V4MAPPED</constant></term>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt This is used with an

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <parameter>af</parameter>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt of AF_INET6, and causes IPv4 addresses to be returned as

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt IPv4-mapped

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt IPv6 addresses.

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </para>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </listitem>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </varlistentry>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <varlistentry>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <term><constant>AI_ALL</constant></term>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt This is used with an

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <parameter>af</parameter>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt of AF_INET6, and causes all known addresses (IPv6 and IPv4) to

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt be returned.

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt If AI_V4MAPPED is also set, the IPv4 addresses are return as

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt mapped

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt IPv6 addresses.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </para>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </listitem>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </varlistentry>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <term><constant>AI_ADDRCONFIG</constant></term>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Only return an IPv6 or IPv4 address if here is an active network

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt interface of that type. This is not currently implemented

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt in the BIND 9 lightweight resolver, and the flag is ignored.

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </para>

a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <term><constant>AI_DEFAULT</constant></term>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt This default sets the

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <constant>AI_V4MAPPED</constant>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt and

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <constant>AI_ADDRCONFIG</constant>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt flag bits.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </para>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </listitem>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </varlistentry>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </variablelist>

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </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>

</refsect1>

<refsect1>

<title>RETURN VALUES</title>

<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>

</refsect1>

<refsect1>

<title>SEE ALSO</title>

<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>

</refsect1>

</refentry><!--