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

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt<refentry>

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt<refentryinfo>

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt<date>Jun 30, 2000</date>

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt</refentryinfo>

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt<refmeta>

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt <refentrytitle>lwres_resutil</refentrytitle>

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt <manvolnum>3</manvolnum>

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt <refmiscinfo>BIND9</refmiscinfo>

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt</refmeta>

591389c7d44e5ca20c357627dd179772cfefaaccEvan Hunt

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

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

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

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