582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<refentry>

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentryinfo>

cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User

f9aef05653eeb454c489d5bd2bde6daab774ad4aTinderbox User

50066670817cdf9e86c832066d73715232b29680Tinderbox User<date>Jun 30, 2000</date>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</refentryinfo>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<refmeta>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<refentrytitle>lwres_getipnode</refentrytitle>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<manvolnum>3</manvolnum>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<refmiscinfo>BIND9</refmiscinfo>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</refmeta>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<refnamediv>

f9aef05653eeb454c489d5bd2bde6daab774ad4aTinderbox User<refname>lwres_getipnodebyname</refname>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<refname>lwres_getipnodebyaddr</refname>

50066670817cdf9e86c832066d73715232b29680Tinderbox User<refname>lwres_freehostent</refname>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<refpurpose>lightweight resolver nodename / address translation API</refpurpose>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</refnamediv>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<refsynopsisdiv>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<funcsynopsis>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<funcprototype>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<funcdef>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userstruct hostent *

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<function>lwres_getipnodebyname</function></funcdef>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<paramdef>const char *name</paramdef>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<paramdef>int af</paramdef>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<paramdef>int flags</paramdef>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<paramdef>int *error_num</paramdef>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</funcprototype>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<funcprototype>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<funcdef>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userstruct hostent *

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<function>lwres_getipnodebyaddr</function></funcdef>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<paramdef>const void *src</paramdef>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<paramdef>size_t len</paramdef>

b27ce68bae92006e2ad7a9b75602c6385e529c3bAutomatic Updater<paramdef>int af</paramdef>

922312472e2e05ebc64993d465999c5351b83036Automatic Updater<paramdef>int *error_num</paramdef>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</funcprototype>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<funcprototype>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<funcdef>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Uservoid

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<function>lwres_freehostent</function></funcdef>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<paramdef>struct hostent *he</paramdef>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</funcprototype>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</funcsynopsis>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</refsynopsisdiv>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<refsect1>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<title>DESCRIPTION</title>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<para>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsThese functions perform thread safe, protocol independent

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Usernodename-to-address and address-to-nodename

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewstranslation as defined in RFC2553.

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</para>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<para>

0e9e255d1643375056aa9ed7fe2a279713ffae78Automatic UpdaterThey use a

cd791043c8a6edbcacc2392575a9816d19b8157cTinderbox User<type>struct hostent</type>

cd791043c8a6edbcacc2392575a9816d19b8157cTinderbox Userwhich is defined in

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<filename>namedb.h</filename>:

481870b95fee976541f4fe455c0ef2dbeab3ec7aTinderbox User

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<programlisting>

481870b95fee976541f4fe455c0ef2dbeab3ec7aTinderbox Userstruct hostent {

481870b95fee976541f4fe455c0ef2dbeab3ec7aTinderbox User char *h_name; /* official name of host */

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User char **h_aliases; /* alias list */

e839bf134fb138920d4833cf05cb8b8906787a8dAutomatic Updater int h_addrtype; /* host address type */

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User int h_length; /* length of address */

e839bf134fb138920d4833cf05cb8b8906787a8dAutomatic Updater char **h_addr_list; /* list of addresses from name server */

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User};

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater#define h_addr h_addr_list[0] /* address, for backward compatibility */

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</programlisting>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater</para>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater<para>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic UpdaterThe members of this structure are:

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<variablelist>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater<varlistentry><term><constant>h_name</constant></term>

795a316ec568b2470aab18b9481443966047652eAutomatic Updater<listitem>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<para>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic UpdaterThe official (canonical) name of the host.

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater</para>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater</listitem>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater<varlistentry><term><constant>h_aliases</constant></term>

795a316ec568b2470aab18b9481443966047652eAutomatic Updater<listitem>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<para>

795a316ec568b2470aab18b9481443966047652eAutomatic UpdaterA NULL-terminated array of alternate names (nicknames) for the host.

795a316ec568b2470aab18b9481443966047652eAutomatic Updater</para>

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</listitem>

795a316ec568b2470aab18b9481443966047652eAutomatic Updater<varlistentry><term><constant>h_addrtype</constant></term>

795a316ec568b2470aab18b9481443966047652eAutomatic Updater<listitem>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<para>

795a316ec568b2470aab18b9481443966047652eAutomatic UpdaterThe type of address being returned - usually

795a316ec568b2470aab18b9481443966047652eAutomatic Updater<type>PF_INET</type>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Useror

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater<type>PF_INET6</type>.

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User

6478b87fd23bcd3ab74c25b261021fe19a239c4fTinderbox User</para>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater</listitem>

9d557856c2a19ec95ee73245f60a92f8675cf5baTinderbox User<varlistentry><term><constant>h_length</constant></term>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<listitem>

ca67ebfe9eef0b8f04179f7e511a19e0337a5422Automatic Updater<para>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserThe length of the address in bytes.

ca67ebfe9eef0b8f04179f7e511a19e0337a5422Automatic Updater</para>

ca67ebfe9eef0b8f04179f7e511a19e0337a5422Automatic Updater</listitem>

ca67ebfe9eef0b8f04179f7e511a19e0337a5422Automatic Updater<varlistentry><term><constant>h_addr_list</constant></term>

163af735c2082a024167be111d27bd5b5ff4f462Automatic Updater<listitem>

481870b95fee976541f4fe455c0ef2dbeab3ec7aTinderbox User<para>

481870b95fee976541f4fe455c0ef2dbeab3ec7aTinderbox UserA

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<type>NULL</type>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsterminated array of network addresses for the host.

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserHost addresses are returned in network byte order.

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</para>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater</listitem>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</variablelist>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</para>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<para>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater<function>lwres_getipnodebyname()</function>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updaterlooks up addresses of protocol family

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<parameter>af</parameter>

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userfor the hostname

0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater<parameter>name</parameter>.

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User

6f1205897504b8f50b1785975482c995888dd630Tinderbox UserThe

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<parameter>flags</parameter>

6f1205897504b8f50b1785975482c995888dd630Tinderbox Userparameter contains ORed flag bits to

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userspecify the types of addresses that are searched

6f1205897504b8f50b1785975482c995888dd630Tinderbox Userfor, and the types of addresses that are returned.

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserThe flag bits are:

6f1205897504b8f50b1785975482c995888dd630Tinderbox User<variablelist>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<varlistentry><term><constant>AI_V4MAPPED</constant></term>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<listitem>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<para>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserThis is used with an

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<parameter>af</parameter>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userof AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsIPv6 addresses.

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</para>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</listitem>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<varlistentry><term><constant>AI_ALL</constant></term>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<listitem>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<para>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserThis is used with an

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<parameter>af</parameter>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsof AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserIf AI_V4MAPPED is also set, the IPv4 addresses are return as mapped

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsIPv6 addresses.

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</para>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</listitem>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<varlistentry><term><constant>AI_ADDRCONFIG</constant></term>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<listitem>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<para>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsOnly return an IPv6 or IPv4 address if here is an active network

b27ce68bae92006e2ad7a9b75602c6385e529c3bAutomatic Updaterinterface of that type. This is not currently implemented

922312472e2e05ebc64993d465999c5351b83036Automatic Updaterin the BIND 9 lightweight resolver, and the flag is ignored.

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</para>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</listitem>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<varlistentry><term><constant>AI_DEFAULT</constant></term>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<listitem>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<para>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsThis default sets the

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<constant>AI_V4MAPPED</constant>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userand

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<constant>AI_ADDRCONFIG</constant>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userflag bits.

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</para>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</listitem>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</variablelist>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</para>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<para>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<function>lwres_getipnodebyaddr()</function>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userperforms a reverse lookup

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsof address

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<parameter>src</parameter>

163af735c2082a024167be111d27bd5b5ff4f462Automatic Updaterwhich is

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<parameter>len</parameter>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsbytes long.

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<parameter>af</parameter>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsdenotes the protocol family, typically

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<type>PF_INET</type>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsor

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<type>PF_INET6</type>.

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews</para>

f9aef05653eeb454c489d5bd2bde6daab774ad4aTinderbox User<para>

cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User<function>lwres_freehostent()</function>

50066670817cdf9e86c832066d73715232b29680Tinderbox Userreleases all the memory associated with

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsthe

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<type>struct hostent</type>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewspointer

f9aef05653eeb454c489d5bd2bde6daab774ad4aTinderbox User<parameter>he</parameter>.

f9aef05653eeb454c489d5bd2bde6daab774ad4aTinderbox User

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsAny memory allocated for the

50066670817cdf9e86c832066d73715232b29680Tinderbox User<constant>h_name</constant>,

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<constant>h_addr_list</constant>

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsand

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<constant>h_aliases</constant>

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntis freed, as is the memory for the

582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews<type>hostent</type>

922312472e2e05ebc64993d465999c5351b83036Automatic Updaterstructure 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 approriate 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><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><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><term><constant>NO_RECOVERY</constant></term>

<listitem>

<para>

An unexpected failure occurred, and retrying the request

is pointless.

</para>

</listitem>

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