<refentry xmlns="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_resutil</refentrytitle>

<manvolnum>3</manvolnum>

<refmiscinfo>BIND9</refmiscinfo>

</refmeta>

<docinfo>

<copyright>

<year>2004</year>

<year>2005</year>

<year>2007</year>

<year>2014</year>

<year>2015</year>

<year>2016</year>

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

</copyright>

<copyright>

<year>2000</year>

<year>2001</year>

<holder>Internet Software Consortium.</holder>

</copyright>

</docinfo>

<refnamediv>

<refname>lwres_string_parse</refname>

<refname>lwres_addr_parse</refname>

<refname>lwres_getaddrsbyname</refname>

<refname>lwres_getnamebyaddr</refname>

<refpurpose>lightweight resolver utility functions</refpurpose>

</refnamediv>

<refsynopsisdiv>

<funcsynopsis>

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

<funcprototype>

<funcdef>

lwres_result_t

<function>lwres_string_parse</function></funcdef>

<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

<paramdef>char **<parameter>c</parameter></paramdef>

<paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>

lwres_result_t

<function>lwres_addr_parse</function></funcdef>

<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

<paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>

lwres_result_t

<function>lwres_getaddrsbyname</function></funcdef>

<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

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

<paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef>

<paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>

lwres_result_t

<function>lwres_getnamebyaddr</function></funcdef>

<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

<paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef>

<paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef>

<paramdef>const unsigned char *<parameter>addr</parameter></paramdef>

<paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>

</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsection><info><title>DESCRIPTION</title></info>

<para><function>lwres_string_parse()</function>

retrieves a DNS-encoded string starting the current pointer of

lightweight resolver buffer <parameter>b</parameter>: i.e.

<constant>b-&gt;current</constant>. When the function returns,

the address of the first byte of the encoded string is returned

via <parameter>*c</parameter> and the length of that string is

given by <parameter>*len</parameter>. The buffer's current

pointer is advanced to point at the character following the

string length, the encoded string, and the trailing

<type>NULL</type> character.

</para>

<para><function>lwres_addr_parse()</function>

extracts an address from the buffer <parameter>b</parameter>.

The buffer's current pointer <constant>b-&gt;current</constant>

is presumed to point at an encoded address: the address preceded

by a 32-bit protocol family identifier and a 16-bit length

field. The encoded address is copied to

<constant>addr-&gt;address</constant> and

<constant>addr-&gt;length</constant> indicates the size in bytes

of the address that was copied.

<constant>b-&gt;current</constant> is advanced to point at the

next byte of available data in the buffer following the encoded

address.

</para>

<para><function>lwres_getaddrsbyname()</function>

and <function>lwres_getnamebyaddr()</function> use the

<type>lwres_gnbaresponse_t</type> structure defined below:

</para>

<para><programlisting>

typedef struct {

lwres_uint32_t flags;

lwres_uint16_t naliases;

lwres_uint16_t naddrs;

char *realname;

char **aliases;

lwres_uint16_t realnamelen;

lwres_uint16_t *aliaslen;

lwres_addrlist_t addrs;

void *base;

size_t baselen;

} lwres_gabnresponse_t;

</programlisting></para>

<para>

The contents of this structure are not manipulated directly but

they are controlled through the

<citerefentry>

<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>

functions.

</para>

<para>

The lightweight resolver uses

<function>lwres_getaddrsbyname()</function> to perform

forward lookups.

Hostname <parameter>name</parameter> is looked up using the

resolver

context <parameter>ctx</parameter> for memory allocation.

<parameter>addrtypes</parameter> is a bitmask indicating

which type of

addresses are to be looked up. Current values for this bitmask are

<type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and

<type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the

lookup are returned in <parameter>*structp</parameter>.

</para>

<para><function>lwres_getnamebyaddr()</function>

performs reverse lookups. Resolver context

<parameter>ctx</parameter> is used for memory allocation. The

address type is indicated by <parameter>addrtype</parameter>:

<type>LWRES_ADDRTYPE_V4</type> or

<type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is

given by <parameter>addr</parameter> and its length is

<parameter>addrlen</parameter> bytes. The result of the

function call is made available through

<parameter>*structp</parameter>.

</para>

</refsection>

<refsection><info><title>RETURN VALUES</title></info>

<para>

Successful calls to

<function>lwres_string_parse()</function>

and

<function>lwres_addr_parse()</function>

return

<errorcode>LWRES_R_SUCCESS.</errorcode>

Both functions return

<errorcode>LWRES_R_FAILURE</errorcode>

if the buffer is corrupt or

<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>

if the buffer has less space than expected for the components of the

encoded string or address.

</para>

<para><function>lwres_getaddrsbyname()</function>

returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it

returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname

<parameter>name</parameter> could not be found.

</para>

<para><errorcode>LWRES_R_SUCCESS</errorcode>

is returned by a successful call to

<function>lwres_getnamebyaddr()</function>.

</para>

<para>

Both

<function>lwres_getaddrsbyname()</function>

and

<function>lwres_getnamebyaddr()</function>

return

<errorcode>LWRES_R_NOMEMORY</errorcode>

when memory allocation requests fail and

<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>

if the buffers used for sending queries and receiving replies are too

small.

</para>

</refsection>

<refsection><info><title>SEE ALSO</title></info>

<para><citerefentry>

<refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>.

</para>

</refsection>

</refentry>