992413f4053d9470046876b234fe094062b730b7Garrett D'Amore<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore [<!ENTITY mdash "&#8212;">]>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore<refentry>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refentryinfo>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <date>June 18, 2007</date>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore </refentryinfo>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refmeta>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refentrytitle>lwres_resutil</refentrytitle>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <manvolnum>3</manvolnum>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refmiscinfo>BIND9</refmiscinfo>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore </refmeta>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <docinfo>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <copyright>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <year>2004</year>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <year>2005</year>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <year>2007</year>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <year>2014</year>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore </copyright>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <copyright>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <year>2000</year>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <year>2001</year>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <holder>Internet Software Consortium.</holder>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore </copyright>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore </docinfo>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refnamediv>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refname>lwres_string_parse</refname>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refname>lwres_addr_parse</refname>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refname>lwres_getaddrsbyname</refname>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refname>lwres_getnamebyaddr</refname>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refpurpose>lightweight resolver utility functions</refpurpose>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore </refnamediv>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refsynopsisdiv>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <funcsynopsis>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore<funcprototype>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <funcdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amorelwres_result_t

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore<function>lwres_string_parse</function></funcdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

7014882c6a3672fd0e5d60200af8643ae53c5928Richard Lowe <paramdef>char **<parameter>c</parameter></paramdef>

7014882c6a3672fd0e5d60200af8643ae53c5928Richard Lowe <paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore </funcprototype>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore<funcprototype>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <funcdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amorelwres_result_t

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore<function>lwres_addr_parse</function></funcdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore </funcprototype>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore<funcprototype>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <funcdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amorelwres_result_t

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore<function>lwres_getaddrsbyname</function></funcdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>const char *<parameter>name</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore </funcprototype>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore<funcprototype>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <funcdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amorelwres_result_t

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore<function>lwres_getnamebyaddr</function></funcdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>const unsigned char *<parameter>addr</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore </funcprototype>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore</funcsynopsis>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore </refsynopsisdiv>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <refsect1>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <title>DESCRIPTION</title>

f4f00ee6d3f12bbd07ebfdc3f8d93438792db6f0Garrett D'Amore

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <para><function>lwres_string_parse()</function>

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore retrieves a DNS-encoded string starting the current pointer of

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore lightweight resolver buffer <parameter>b</parameter>: i.e.

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore <constant>b-&gt;current</constant>. When the function returns,

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore the address of the first byte of the encoded string is returned

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore via <parameter>*c</parameter> and the length of that string is

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore given by <parameter>*len</parameter>. The buffer's current

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore pointer is advanced to point at the character following the

992413f4053d9470046876b234fe094062b730b7Garrett D'Amore 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

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