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

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

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

<refentry>

<refentryinfo>

<date>Jun 30, 2000</date>

</refentryinfo>

<refmeta>

<refentrytitle>lwres_getipnode</refentrytitle>

<manvolnum>3</manvolnum>

<refmiscinfo>BIND9</refmiscinfo>

</refmeta>

<docinfo>

<copyright>

<year>2004</year>

<year>2005</year>

<year>2007</year>

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

</copyright>

<copyright>

<year>2000</year>

<year>2001</year>

<year>2003</year>

<holder>Internet Software Consortium.</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>

<refsect1>

<title>DESCRIPTION</title>

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

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