lwres.html revision 75c0816e8295e180f4bc7f10db3d0d880383bc1c
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
18920d790825d96ca3943aa2dcb6eb80dc611c5fTinderbox User - Copyright (C) 2000, 2001 Internet Software Consortium.
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User - Permission to use, copy, modify, and distribute this software for any
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User - purpose with or without fee is hereby granted, provided that the above
c57668a2fbbe558c1bd21652813616f2f517c469Tinderbox User - copyright notice and this permission notice appear in all copies.
1f4c645185bd8fc70048e0a69eee46193a284e5cTinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox User - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
950d203b64f512b85fcc093ee1e9e3e531a1aea3Tinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
e676a596869d8a80a644c99a848afb53d1c5975eMark Andrews - PERFORMANCE OF THIS SOFTWARE.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<!-- $Id: lwres.html,v 1.13 2005/05/13 03:14:11 marka Exp $ -->
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
e676a596869d8a80a644c99a848afb53d1c5975eMark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<a name="id2456836"></a><div class="titlepage"></div>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<p>lwres — introduction to the lightweight resolver library</p>
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews<div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre></div>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews The BIND 9 lightweight resolver library is a simple, name service
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User independent stub resolver library. It provides hostname-to-address
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews and address-to-hostname lookup services to applications by
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User transmitting lookup requests to a resolver daemon
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <span><strong class="command">lwresd</strong></span>
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User running on the local host. The resover daemon performs the
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews lookup using the DNS or possibly other name service protocols,
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt and returns the results to the application through the library.
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User The library and resolver daemon communicate using a simple
0e573cdd111e060e5f6c18249b5ccacbe8abe278Tinderbox User UDP-based protocol.
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User The lwresd library implements multiple name service APIs.
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User <code class="function">gethostbyaddr()</code>,
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <code class="function">gethostbyname_r()</code>,
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <code class="function">gethostbyaddr_r()</code>,
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <code class="function">getaddrinfo()</code>,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <code class="function">getipnodebyname()</code>,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <code class="function">getipnodebyaddr()</code>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews functions are all supported. To allow the lwres library to coexist
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews with system libraries that define functions of the same name,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews the library defines these functions with names prefixed by
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews To define the standard names, applications must include the
16f6050f29b6b0422cee858e609f65e474e70ef2Tinderbox User <code class="filename"><lwres/netdb.h></code>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews which contains macro definitions mapping the standard function names
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews prefixed ones. Operating system vendors who integrate the lwres
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews library into their base distributions should rename the functions
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews in the library proper so that the renaming macros are not needed.
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt The library also provides a native API consisting of the functions
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt <code class="function">lwres_getaddrsbyname()</code>
95637507c3d47481fbf0a8a8c750a57f944f677fMark Andrews <code class="function">lwres_getnamebyaddr()</code>.
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt These may be called by applications that require more detailed
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt control over the lookup process than the standard functions
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt In addition to these name service independent address lookup
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt functions, the library implements a new, experimental API
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User for looking up arbitrary DNS resource records, using the
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews <code class="function">lwres_getaddrsbyname()</code>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews Finally, there is a low-level API for converting lookup
18920d790825d96ca3943aa2dcb6eb80dc611c5fTinderbox User requests and responses to and from raw lwres protocol packets.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews This API can be used by clients requiring nonblocking operation,
7a6494cfb6cc7d3f67af07359561e05e6bb8c0edTinderbox User and is also used when implementing the server side of the lwres
0e573cdd111e060e5f6c18249b5ccacbe8abe278Tinderbox User protocol, for example in the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span><strong class="command">lwresd</strong></span>
18920d790825d96ca3943aa2dcb6eb80dc611c5fTinderbox User resolver daemon. The use of this low-level API in clients
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews and servers is outlined in the following sections.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<a name="id2514318"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User When a client program wishes to make an lwres request using the
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews native low-level API, it typically performs the following
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User sequence of actions.
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews (1) Allocate or use an existing <span class="type">lwres_packet_t</span>,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User (2) Set <em class="structfield"><code>pkt.recvlength</code></em> to the maximum length
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson we will accept.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User This is done so the receiver of our packets knows how large our receive
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews buffer is. The "default" is a constant in
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson (3) Set <em class="structfield"><code>pkt.serial</code></em>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User to a unique serial number. This value is echoed
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews back to the application by the remote server.
28a5dd720187fddb16055a0f64b63a7b66f29f64Mark Andrews (4) Set <em class="structfield"><code>pkt.pktflags</code></em>. Usually this is set to
0e573cdd111e060e5f6c18249b5ccacbe8abe278Tinderbox User (5) Set <em class="structfield"><code>pkt.result</code></em> to 0.
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox User (6) Call <code class="function">lwres_*request_render()</code>,
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox User or marshall in the data using the primitives
fd972434c29fc1169d66594e4cc7697d33036c2bTinderbox User such as <code class="function">lwres_packet_render()</code>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont and storing the packet data.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont (7) Transmit the resulting buffer.
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews (8) Call <code class="function">lwres_*response_parse()</code>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews to parse any packets received.
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews (9) Verify that the opcode and serial match a request, and process the
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews packet specific information contained in the body.
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews<a name="id2514467"></a><h2>SERVER-SIDE LOW-LEVEL API CALL FLOW</h2>
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User When implementing the server side of the lightweight resolver
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews protocol using the lwres library, a sequence of actions like the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews following is typically involved in processing each request packet.
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews Note that the same <span class="type">lwres_packet_t</span> is used
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews in both the <code class="function">_parse()</code> and <code class="function">_render()</code> calls,
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User with only a few modifications made
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox User to the packet header's contents between uses. This method is
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater as it keeps the serial, opcode, and other fields correct.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews (1) When a packet is received, call <code class="function">lwres_*request_parse()</code> to
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User unmarshall it. This returns a <span class="type">lwres_packet_t</span> (also called <code class="varname">pkt</code>, below)
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater as well as a data specific type, such as <span class="type">lwres_gabnrequest_t</span>.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User (2) Process the request in the data specific type.
fa0326cc2cf428f67575b6ba3b97b528a31b0010Tinderbox User (3) Set the <em class="structfield"><code>pkt.result</code></em>,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <em class="structfield"><code>pkt.recvlength</code></em> as above. All other fields
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User be left untouched since they were filled in by the <code class="function">*_parse()</code> call
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews above. If using <code class="function">lwres_*response_render()</code>,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <em class="structfield"><code>pkt.pktflags</code></em> will be set up
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews (4) Call the data specific rendering function, such as
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <code class="function">lwres_gabnresponse_render()</code>.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews (5) Send the resulting packet to the client.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<p><span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>,
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <span class="citerefentry"><span class="refentrytitle">lwres_noop</span>(3)</span>,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>,
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <span class="citerefentry"><span class="refentrytitle">lwres_gnba</span>(3)</span>,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <span class="citerefentry"><span class="refentrytitle">lwres_context</span>(3)</span>,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <span class="citerefentry"><span class="refentrytitle">lwres_config</span>(3)</span>,
5f7586ddbd3edd11272cdd30ed613d936129328bTinderbox User <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <span class="citerefentry"><span class="refentrytitle">lwresd</span>(8)</span>.