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

<refentry>

<refentryinfo>

<date>Jun 30, 2000</date>

</refentryinfo>

<refmeta>

<refentrytitle>lwres_resutil</refentrytitle>

<manvolnum>3</manvolnum>

<refmiscinfo>BIND9</refmiscinfo>

</refmeta>

<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 *b</paramdef>

<paramdef>char **c</paramdef>

<paramdef>lwres_uint16_t *len</paramdef>

</funcprototype>

<funcprototype>

<funcdef>

lwres_result_t

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

<paramdef>lwres_buffer_t *b</paramdef>

<paramdef>lwres_addr_t *addr</paramdef>

</funcprototype>

<funcprototype>

<funcdef>

lwres_result_t

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

<paramdef>lwres_context_t *ctx</paramdef>

<paramdef>const char *name</paramdef>

<paramdef>lwres_uint32_t addrtypes</paramdef>

<paramdef>lwres_gabnresponse_t **structp</paramdef>

</funcprototype>

<funcprototype>

<funcdef>

lwres_result_t

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

<paramdef>lwres_context_t *ctx</paramdef>

<paramdef>lwres_uint32_t addrtype</paramdef>

<paramdef>lwres_uint16_t addrlen</paramdef>

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

<paramdef>lwres_gnbaresponse_t **structp</paramdef>

</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsect1>

<title>DESCRIPTION</title>

<para>

<function>lwres_string_parse()</function>

retrieves a DNS-encoded string starting the current pointer of

lightweight resolver buffer

<parameter>b</parameter>:

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

<function>lwres_string_parse()</function>

has an assertion check that

<parameter>b</parameter>

is not

<type>NULL</type>.

</para>

<para>

<function>lwres_addr_parse()</function>

extracts an address from the buffer

<parameter>b</parameter>.

It checks that

<parameter>addr</parameter>

is not null.

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:

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

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

<function>lwres_getaddrsbyname()</function>

checks that its pointer arguments are not

<type>NULL</type>

and that

<parameter>addrtypes</parameter>

is non-zero.

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

Like

<function>lwres_getaddrsbyname()</function>,

<function>lwres_getnamebyaddr()</function>

uses assertion checking to ensure its pointer arguments are not

<type>NULL</type>

and

<parameter>addrtype</parameter>

is not zero.

<function>lwres_getaddrsbyname()</function>

also checks that

<parameter>addrlen</parameter>

is non-zero.

</para>

</refsect1>

<refsect1>

<title>RETURN VALUES</title>

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

</refsect1>

<refsect1>

<title>SEE ALSO</title>

<para>

<citerefentry>

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

</citerefentry>,

<citerefentry>

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

</citerefentry>.

</para>

</refsect1>

</refentry>