25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis [<!ENTITY mdash "&#8212;">]>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis<refentry>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <refentryinfo>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <date>Jun 30, 2000</date>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </refentryinfo>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <refmeta>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <refentrytitle>lwres</refentrytitle>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <manvolnum>3</manvolnum>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <refmiscinfo>BIND9</refmiscinfo>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </refmeta>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <refnamediv>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <refname>lwres</refname>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <refpurpose>introduction to the lightweight resolver library</refpurpose>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </refnamediv>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <docinfo>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <copyright>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <year>2004</year>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <year>2005</year>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <year>2007</year>

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

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </copyright>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <copyright>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <year>2000</year>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <year>2001</year>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <holder>Internet Software Consortium.</holder>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </copyright>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </docinfo>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <refsynopsisdiv>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <funcsynopsis>

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

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis</funcsynopsis>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </refsynopsisdiv>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <refsect1>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <title>DESCRIPTION</title>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis The BIND 9 lightweight resolver library is a simple, name service

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis independent stub resolver library. It provides hostname-to-address

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis and address-to-hostname lookup services to applications by

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis transmitting lookup requests to a resolver daemon

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <command>lwresd</command>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis running on the local host. The resover daemon performs the

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis lookup using the DNS or possibly other name service protocols,

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis and returns the results to the application through the library.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis The library and resolver daemon communicate using a simple

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis UDP-based protocol.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </refsect1>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <refsect1>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <title>OVERVIEW</title>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis The lwresd library implements multiple name service APIs.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis The standard

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <function>gethostbyname()</function>,

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <function>gethostbyaddr()</function>,

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <function>gethostbyname_r()</function>,

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <function>gethostbyaddr_r()</function>,

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <function>getaddrinfo()</function>,

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <function>getipnodebyname()</function>,

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis and

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <function>getipnodebyaddr()</function>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis functions are all supported. To allow the lwres library to coexist

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis with system libraries that define functions of the same name,

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis the library defines these functions with names prefixed by

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <literal>lwres_</literal>.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis To define the standard names, applications must include the

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis header file

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <filename>&lt;lwres/netdb.h&gt;</filename>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis which contains macro definitions mapping the standard function names

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis into

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <literal>lwres_</literal>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis prefixed ones. Operating system vendors who integrate the lwres

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis library into their base distributions should rename the functions

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis in the library proper so that the renaming macros are not needed.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis The library also provides a native API consisting of the functions

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <function>lwres_getaddrsbyname()</function>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis and

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <function>lwres_getnamebyaddr()</function>.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis These may be called by applications that require more detailed

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis control over the lookup process than the standard functions

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis provide.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis In addition to these name service independent address lookup

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis functions, the library implements a new, experimental API

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis for looking up arbitrary DNS resource records, using the

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <function>lwres_getaddrsbyname()</function>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis function.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis Finally, there is a low-level API for converting lookup

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis requests and responses to and from raw lwres protocol packets.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis This API can be used by clients requiring nonblocking operation,

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis and is also used when implementing the server side of the lwres

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis protocol, for example in the

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <command>lwresd</command>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis resolver daemon. The use of this low-level API in clients

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis and servers is outlined in the following sections.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </refsect1>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <refsect1>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis When a client program wishes to make an lwres request using the

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis native low-level API, it typically performs the following

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis sequence of actions.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis (1) Allocate or use an existing <type>lwres_packet_t</type>,

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis called <varname>pkt</varname> below.

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis </para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis <para>

25c28e83beb90e7c80452a7c818c5e6f73a07dc8Piotr Jasiukajtis (2) Set <structfield>pkt.recvlength</structfield> to the maximum length

we will accept.

This is done so the receiver of our packets knows how large our receive

buffer is. The "default" is a constant in

<filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.

</para>

<para>

(3) Set <structfield>pkt.serial</structfield>

to a unique serial number. This value is echoed

back to the application by the remote server.

</para>

<para>

(4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to

0.

</para>

<para>

(5) Set <structfield>pkt.result</structfield> to 0.

</para>

<para>

(6) Call <function>lwres_*request_render()</function>,

or marshall in the data using the primitives

such as <function>lwres_packet_render()</function>

and storing the packet data.

</para>

<para>

(7) Transmit the resulting buffer.

</para>

<para>

(8) Call <function>lwres_*response_parse()</function>

to parse any packets received.

</para>

<para>

(9) Verify that the opcode and serial match a request, and process the

packet specific information contained in the body.

</para>

</refsect1>

<refsect1>

<title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title>

<para>

When implementing the server side of the lightweight resolver

protocol using the lwres library, a sequence of actions like the

following is typically involved in processing each request packet.

</para>

<para>

Note that the same <type>lwres_packet_t</type> is used

in both the <function>_parse()</function> and <function>_render()</function> calls,

with only a few modifications made

to the packet header's contents between uses. This method is

recommended

as it keeps the serial, opcode, and other fields correct.

</para>

<para>

(1) When a packet is received, call <function>lwres_*request_parse()</function> to

unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)

as well as a data specific type, such as <type>lwres_gabnrequest_t</type>.

</para>

<para>

(2) Process the request in the data specific type.

</para>

<para>

(3) Set the <structfield>pkt.result</structfield>,

<structfield>pkt.recvlength</structfield> as above. All other fields

can

be left untouched since they were filled in by the <function>*_parse()</function> call

above. If using <function>lwres_*response_render()</function>,

<structfield>pkt.pktflags</structfield> will be set up

properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be

set.

</para>

<para>

(4) Call the data specific rendering function, such as

<function>lwres_gabnresponse_render()</function>.

</para>

<para>

(5) Send the resulting packet to the client.

</para>

<para></para>

</refsect1>

<refsect1>

<title>SEE ALSO</title>

<para><citerefentry>

<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>,

<citerefentry>

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

</citerefentry>,

<citerefentry>

<refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>

</citerefentry>.

</para>

</refsect1>

</refentry><!--