1N/A<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

1N/A "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

1N/A [<!ENTITY mdash "&#8212;">]>

1N/A

1N/A<refentry>

1N/A

1N/A <refentryinfo>

1N/A <date>Jun 30, 2000</date>

1N/A </refentryinfo>

1N/A

1N/A <refmeta>

1N/A <refentrytitle>lwres_getipnode</refentrytitle>

1N/A <manvolnum>3</manvolnum>

1N/A <refmiscinfo>BIND9</refmiscinfo>

1N/A </refmeta>

1N/A

1N/A <docinfo>

1N/A <copyright>

1N/A <year>2004</year>

1N/A <year>2005</year>

1N/A <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

1N/A </copyright>

1N/A <copyright>

1N/A <year>2000</year>

1N/A <year>2001</year>

1N/A <year>2003</year>

1N/A <holder>Internet Software Consortium.</holder>

1N/A </copyright>

1N/A </docinfo>

1N/A

1N/A <refnamediv>

1N/A <refname>lwres_getipnodebyname</refname>

1N/A <refname>lwres_getipnodebyaddr</refname>

1N/A <refname>lwres_freehostent</refname>

1N/A <refpurpose>lightweight resolver nodename / address translation API</refpurpose>

1N/A </refnamediv>

1N/A <refsynopsisdiv>

1N/A <funcsynopsis>

1N/A<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>

1N/A<funcprototype>

1N/A <funcdef>

1N/Astruct hostent *

1N/A<function>lwres_getipnodebyname</function></funcdef>

1N/A <paramdef>const char *<parameter>name</parameter></paramdef>

1N/A <paramdef>int <parameter>af</parameter></paramdef>

1N/A <paramdef>int <parameter>flags</parameter></paramdef>

1N/A <paramdef>int *<parameter>error_num</parameter></paramdef>

1N/A </funcprototype>

1N/A<funcprototype>

1N/A <funcdef>

1N/Astruct hostent *

1N/A<function>lwres_getipnodebyaddr</function></funcdef>

1N/A <paramdef>const void *<parameter>src</parameter></paramdef>

1N/A <paramdef>size_t <parameter>len</parameter></paramdef>

1N/A <paramdef>int <parameter>af</parameter></paramdef>

1N/A <paramdef>int *<parameter>error_num</parameter></paramdef>

1N/A </funcprototype>

1N/A<funcprototype>

1N/A <funcdef>

1N/Avoid

1N/A<function>lwres_freehostent</function></funcdef>

1N/A <paramdef>struct hostent *<parameter>he</parameter></paramdef>

1N/A </funcprototype>

1N/A</funcsynopsis>

1N/A </refsynopsisdiv>

1N/A

1N/A <refsect1>

1N/A <title>DESCRIPTION</title>

1N/A

1N/A <para>

1N/A These functions perform thread safe, protocol independent

1N/A nodename-to-address and address-to-nodename

1N/A translation as defined in RFC2553.

1N/A </para>

1N/A

1N/A <para>

1N/A They use a

1N/A <type>struct hostent</type>

1N/A which is defined in

1N/A <filename>namedb.h</filename>:

1N/A </para>

1N/A <para><programlisting>

1N/Astruct hostent {

1N/A char *h_name; /* official name of host */

1N/A char **h_aliases; /* alias list */

1N/A int h_addrtype; /* host address type */

1N/A int h_length; /* length of address */

1N/A char **h_addr_list; /* list of addresses from name server */

1N/A};

1N/A#define h_addr h_addr_list[0] /* address, for backward compatibility */

1N/A</programlisting>

1N/A </para>

1N/A

1N/A <para>

1N/A The members of this structure are:

1N/A <variablelist>

1N/A <varlistentry>

1N/A <term><constant>h_name</constant></term>

1N/A <listitem>

1N/A <para>

1N/A The official (canonical) name of the host.

1N/A </para>

1N/A </listitem>

1N/A </varlistentry>

1N/A <varlistentry>

1N/A <term><constant>h_aliases</constant></term>

1N/A <listitem>

1N/A <para>

1N/A A NULL-terminated array of alternate names (nicknames) for the

1N/A host.

1N/A </para>

1N/A </listitem>

1N/A </varlistentry>

1N/A <varlistentry>

1N/A <term><constant>h_addrtype</constant></term>

1N/A <listitem>

1N/A <para>

1N/A The type of address being returned - usually

1N/A <type>PF_INET</type>

1N/A or

1N/A <type>PF_INET6</type>.

1N/A

1N/A </para>

1N/A </listitem>

1N/A </varlistentry>

1N/A <varlistentry>

1N/A <term><constant>h_length</constant></term>

1N/A <listitem>

1N/A <para>

1N/A The length of the address in bytes.

1N/A </para>

1N/A </listitem>

1N/A </varlistentry>

1N/A <varlistentry>

1N/A <term><constant>h_addr_list</constant></term>

1N/A <listitem>

1N/A <para>

1N/A A

1N/A <type>NULL</type>

1N/A terminated array of network addresses for the host.

1N/A Host addresses are returned in network byte order.

1N/A </para>

1N/A </listitem>

1N/A </varlistentry>

1N/A </variablelist>

1N/A </para>

1N/A

1N/A <para><function>lwres_getipnodebyname()</function>

1N/A looks up addresses of protocol family <parameter>af</parameter>

1N/A for the hostname <parameter>name</parameter>. The

1N/A <parameter>flags</parameter> parameter contains ORed flag bits

1N/A to specify the types of addresses that are searched for, and the

1N/A types of addresses that are returned. The flag bits are:

1N/A

1N/A <variablelist>

1N/A <varlistentry>

1N/A <term><constant>AI_V4MAPPED</constant></term>

1N/A <listitem>

1N/A <para>

1N/A This is used with an

1N/A <parameter>af</parameter>

1N/A of AF_INET6, and causes IPv4 addresses to be returned as

1N/A IPv4-mapped

1N/A IPv6 addresses.

1N/A </para>

1N/A </listitem>

1N/A </varlistentry>

1N/A <varlistentry>

1N/A <term><constant>AI_ALL</constant></term>

1N/A <listitem>

1N/A <para>

1N/A This is used with an

1N/A <parameter>af</parameter>

1N/A of AF_INET6, and causes all known addresses (IPv6 and IPv4) to

1N/A be returned.

1N/A If AI_V4MAPPED is also set, the IPv4 addresses are return as

1N/A mapped

1N/A IPv6 addresses.

1N/A </para>

1N/A </listitem>

1N/A </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>

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