lwres.docbook revision ddccd5811feff696ba460dabfb666ce61040f545
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - Copyright (C) 2000, 2001 Internet Software Consortium.
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - Permission to use, copy, modify, and distribute this software for any
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - purpose with or without fee is hereby granted, provided that the above
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - copyright notice and this permission notice appear in all copies.
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
7190e58eec40192c9719d2f2593471eda14e7e7cfuankg<!-- $Id: lwres.docbook,v 1.2 2001/03/31 00:08:00 gson Exp $ -->
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg<refentryinfo>
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg</refentryinfo>
95ca7cc2aa11b41497ffab3a1003bc09d24b6bc1fuankg<refnamediv>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<refpurpose>introduction to the lightweight resolver library</refpurpose>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes</refnamediv>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<refsynopsisdiv>
70953fb44a7140fe206c3a5f011e24209c8c5c6abnicholes<funcsynopsis>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes</funcsynopsis>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes</refsynopsisdiv>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThe BIND 9 lightweight resolver library is a simple, name service
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesindependent stub resolver library. It provides hostname-to-address
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesand address-to-hostname lookup services to applications by
0662ed52e814f8f08ef0e09956413a792584eddffuankgtransmitting lookup requests to a resolver daemon
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesrunning on the local host. The resover daemon performs the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeslookup using the DNS or possibly other name service protocols,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesand returns the results to the application through the library.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThe library and resolver daemon communicate using a simple
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesUDP-based protocol.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThe lwresd library implements multiple name service APIs.
b387b9d37fc71c534f4718777454a8f5a1169017fuankgfunctions are all supported. To allow the lwres library to coexist
b387b9d37fc71c534f4718777454a8f5a1169017fuankgwith system libraries that define functions of the same name,
b387b9d37fc71c534f4718777454a8f5a1169017fuankgthe library defines these functions with names prefixed by
8d6e239d0e0aa0593fd93b4fef193d8c51b61b3cfuankgTo define the standard names, applications must include the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeswhich contains macro definitions mapping the standard function names
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesprefixed ones. Operating system vendors who integrate the lwres
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeslibrary into their base distributions should rename the functions
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesin the library proper so that the renaming macros are not needed.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThe library also provides a native API consisting of the functions
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThese may be called by applications that require more detailed
bb2b38cd44b032118359afbc743efbea12f48e61bnicholescontrol over the lookup process than the standard functions
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesIn addition to these name service independent address lookup
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesfunctions, the library implements a new, experimental API
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesfor looking up arbitrary DNS resource records, using the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesFinally, there is a low-level API for converting lookup
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesrequests and responses to and from raw lwres protocol packets.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThis API can be used by clients requiring nonblocking operation,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesand is also used when implementing the server side of the lwres
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesprotocol, for example in the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesresolver daemon. The use of this low-level API in clients
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesand servers is outlined in the following sections.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesWhen a client program wishes to make an lwres request using the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesnative low-level API, it typically performs the following
bb2b38cd44b032118359afbc743efbea12f48e61bnicholessequence of actions.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes(1) Allocate or use an existing <type>lwres_packet_t</type>,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes(2) Set <structfield>pkt.recvlength</structfield> to the maximum length we will accept.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThis is done so the receiver of our packets knows how large our receive
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesbuffer is. The "default" is a constant in
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesto a unique serial number. This value is echoed
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesback to the application by the remote server.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes(4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to 0.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes(5) Set <structfield>pkt.result</structfield> to 0.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes(6) Call <function>lwres_*request_render()</function>,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesor marshall in the data using the primitives
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesand storing the packet data.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes(7) Transmit the resulting buffer.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesto parse any packets received.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes(9) Verify that the opcode and serial match a request, and process the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholespacket specific information contained in the body.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesWhen implementing the server side of the lightweight resolver
b387b9d37fc71c534f4718777454a8f5a1169017fuankgprotocol using the lwres library, a sequence of actions like the
41022996c916eb4ab2ec3204eb491b64779eb100bnicholesfollowing is typically involved in processing each request packet.
41022996c916eb4ab2ec3204eb491b64779eb100bnicholesNote that the same <type>lwres_packet_t</type> is used
41022996c916eb4ab2ec3204eb491b64779eb100bnicholesin both the <function>_parse()</function> and <function>_render()</function> calls,
036436f4f4cdcd76186c0058891216545967043bbnicholeswith only a few modifications made
41022996c916eb4ab2ec3204eb491b64779eb100bnicholesto the packet header's contents between uses. This method is recommended
41022996c916eb4ab2ec3204eb491b64779eb100bnicholesas it keeps the serial, opcode, and other fields correct.
0662ed52e814f8f08ef0e09956413a792584eddffuankg(1) When a packet is received, call <function>lwres_*request_parse()</function> to
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesunmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)
ce22ce4743d79a889dca64df4459c598e2c188c7fuankgas well as a data specific type, such as <type>lwres_gabnrequest_t</type>.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes(2) Process the request in the data specific type.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<structfield>pkt.recvlength</structfield> as above. All other fields can
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesbe left untouched since they were filled in by the <function>*_parse()</function> call
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesabove. If using <function>lwres_*response_render()</function>,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<structfield>pkt.pktflags</structfield> will be set up
0662ed52e814f8f08ef0e09956413a792584eddffuankgproperly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes(4) Call the data specific rendering function, such as
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes(5) Send the resulting packet to the client.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<citerefentry>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
ce22ce4743d79a889dca64df4459c598e2c188c7fuankg</citerefentry>,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<citerefentry>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
ce22ce4743d79a889dca64df4459c598e2c188c7fuankg</citerefentry>,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<citerefentry>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes</citerefentry>,
b387b9d37fc71c534f4718777454a8f5a1169017fuankg<citerefentry>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes</citerefentry>,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<citerefentry>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes</citerefentry>,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<citerefentry>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes</citerefentry>,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<citerefentry>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes</citerefentry>,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<citerefentry>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes</citerefentry>,
286fed73f9d1474652034465d4048247c6e7341fbnicholes<citerefentry>
be88e49281c5becee364ab9c6a0576f9b9844e0fbnicholes<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes</citerefentry>,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<citerefentry>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
56ab8639aed4d3b2f031d9c1160c5f40af01bdebjerenkrantz</citerefentry>.