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

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<refentry>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont <refentryinfo>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<date>Jun 30, 2000</date>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</refentryinfo>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont <refmeta>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont <refentrytitle>lwres</refentrytitle>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont <manvolnum>3</manvolnum>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont <refmiscinfo>BIND9</refmiscinfo>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont </refmeta>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<refnamediv>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<refname>lwres</refname>

938440694b33cd752e9e4b71a526368b4811c177Tinderbox User<refpurpose>introduction to the lightweight resolver library</refpurpose>

19c7b1a0293498a3e36692c59646ed6e15ffc8d0Tinderbox User</refnamediv>

f1a2709aad7baa4161fdb6f63edf99b0150af252Evan Hunt

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<refsynopsisdiv>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<funcsynopsis>

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

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</funcsynopsis>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</refsynopsisdiv>

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<refsect1>

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<title>DESCRIPTION</title>

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<para>

14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThe BIND 9 lightweight resolver library is a simple, name service

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntindependent stub resolver library. It provides hostname-to-address

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntand address-to-hostname lookup services to applications by

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunttransmitting lookup requests to a resolver daemon

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<command>lwresd</command>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontrunning on the local host. The resover daemon performs the

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontlookup using the DNS or possibly other name service protocols,

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntand returns the results to the application through the library.

30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark AndrewsThe library and resolver daemon communicate using a simple

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis DupontUDP-based protocol.

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</refsect1>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont

f1a2709aad7baa4161fdb6f63edf99b0150af252Evan Hunt<refsect1>

f1a2709aad7baa4161fdb6f63edf99b0150af252Evan Hunt<title>OVERVIEW</title>

f1a2709aad7baa4161fdb6f63edf99b0150af252Evan Hunt<para>

f1a2709aad7baa4161fdb6f63edf99b0150af252Evan HuntThe lwresd library implements multiple name service APIs.

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis DupontThe standard

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<function>gethostbyname()</function>,

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<function>gethostbyaddr()</function>,

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<function>gethostbyname_r()</function>,

30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews<function>gethostbyaddr_r()</function>,

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<function>getaddrinfo()</function>,

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<function>getipnodebyname()</function>,

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontand

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<function>getipnodebyaddr()</function>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontfunctions are all supported. To allow the lwres library to coexist

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontwith system libraries that define functions of the same name,

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontthe library defines these functions with names prefixed by

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<literal>lwres_</literal>.

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis DupontTo define the standard names, applications must include the

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontheader file

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<filename>&lt;lwres/netdb.h&gt;</filename>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontwhich contains macro definitions mapping the standard function names

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontinto

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<literal>lwres_</literal>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontprefixed ones. Operating system vendors who integrate the lwres

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontlibrary into their base distributions should rename the functions

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontin the library proper so that the renaming macros are not needed.

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis DupontThe library also provides a native API consisting of the functions

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<function>lwres_getaddrsbyname()</function>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontand

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<function>lwres_getnamebyaddr()</function>.

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis DupontThese may be called by applications that require more detailed

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontcontrol over the lookup process than the standard functions

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontprovide.

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis DupontIn addition to these name service independent address lookup

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontfunctions, the library implements a new, experimental API

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontfor looking up arbitrary DNS resource records, using the

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<function>lwres_getaddrsbyname()</function>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontfunction.

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis DupontFinally, there is a low-level API for converting lookup

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontrequests and responses to and from raw lwres protocol packets.

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis DupontThis API can be used by clients requiring nonblocking operation,

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontand is also used when implementing the server side of the lwres

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontprotocol, for example in the

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<command>lwresd</command>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontresolver daemon. The use of this low-level API in clients

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontand servers is outlined in the following sections.

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</refsect1>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<refsect1>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis DupontWhen a client program wishes to make an lwres request using the

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontnative low-level API, it typically performs the following

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontsequence of actions.

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont(1) Allocate or use an existing <type>lwres_packet_t</type>,

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontcalled <varname>pkt</varname> below.

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont(2) Set <structfield>pkt.recvlength</structfield> to the maximum length we will accept.

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

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontbuffer is. The "default" is a constant in

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

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont</para>

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<para>

30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews(3) Set <structfield>pkt.serial</structfield>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontto a unique serial number. This value is echoed

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontback to the application by the remote server.

b0af7cbe9220775e23127f2f38750e4a281ee871Jeremy C. Reed</para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<para>

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

b0af7cbe9220775e23127f2f38750e4a281ee871Jeremy C. Reed</para>

b0af7cbe9220775e23127f2f38750e4a281ee871Jeremy C. Reed<para>

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

b0af7cbe9220775e23127f2f38750e4a281ee871Jeremy C. Reed</para>

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupont<para>

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

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntor marshall in the data using the primitives

a631b30b1ddd8b2ea780371d0d99ba1c05bc7e42Francis Dupontsuch as <function>lwres_packet_render()</function>

14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntand 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>