1135446Strhodes<!-- 2170222Sdougb - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") 3153816Sdougb - Copyright (C) 2000, 2001 Internet Software Consortium. 4153816Sdougb - 5204619Sdougb - Permission to use, copy, modify, and/or distribute this software for any 6135446Strhodes - purpose with or without fee is hereby granted, provided that the above 7135446Strhodes - copyright notice and this permission notice appear in all copies. 8153816Sdougb - 9135446Strhodes - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10135446Strhodes - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11153816Sdougb - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12135446Strhodes - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13135446Strhodes - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14135446Strhodes - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15135446Strhodes - PERFORMANCE OF THIS SOFTWARE. 16135446Strhodes--> 17234010Sdougb<!-- $Id$ --> 18153816Sdougb<html> 19153816Sdougb<head> 20153816Sdougb<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 21153816Sdougb<title>lwres</title> 22170222Sdougb<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> 23153816Sdougb</head> 24153816Sdougb<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> 25234010Sdougb<a name="id2476274"></a><div class="titlepage"></div> 26153816Sdougb<div class="refnamediv"> 27153816Sdougb<h2>Name</h2> 28153816Sdougb<p>lwres — introduction to the lightweight resolver library</p> 29153816Sdougb</div> 30153816Sdougb<div class="refsynopsisdiv"> 31153816Sdougb<h2>Synopsis</h2> 32153816Sdougb<div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre></div> 33153816Sdougb</div> 34153816Sdougb<div class="refsect1" lang="en"> 35234010Sdougb<a name="id2543350"></a><h2>DESCRIPTION</h2> 36153816Sdougb<p> 37170222Sdougb The BIND 9 lightweight resolver library is a simple, name service 38170222Sdougb independent stub resolver library. It provides hostname-to-address 39170222Sdougb and address-to-hostname lookup services to applications by 40170222Sdougb transmitting lookup requests to a resolver daemon 41170222Sdougb <span><strong class="command">lwresd</strong></span> 42170222Sdougb running on the local host. The resover daemon performs the 43170222Sdougb lookup using the DNS or possibly other name service protocols, 44170222Sdougb and returns the results to the application through the library. 45170222Sdougb The library and resolver daemon communicate using a simple 46170222Sdougb UDP-based protocol. 47170222Sdougb </p> 48153816Sdougb</div> 49153816Sdougb<div class="refsect1" lang="en"> 50234010Sdougb<a name="id2543363"></a><h2>OVERVIEW</h2> 51153816Sdougb<p> 52170222Sdougb The lwresd library implements multiple name service APIs. 53170222Sdougb The standard 54170222Sdougb <code class="function">gethostbyname()</code>, 55170222Sdougb <code class="function">gethostbyaddr()</code>, 56170222Sdougb <code class="function">gethostbyname_r()</code>, 57170222Sdougb <code class="function">gethostbyaddr_r()</code>, 58170222Sdougb <code class="function">getaddrinfo()</code>, 59170222Sdougb <code class="function">getipnodebyname()</code>, 60170222Sdougb and 61170222Sdougb <code class="function">getipnodebyaddr()</code> 62170222Sdougb functions are all supported. To allow the lwres library to coexist 63170222Sdougb with system libraries that define functions of the same name, 64170222Sdougb the library defines these functions with names prefixed by 65170222Sdougb <code class="literal">lwres_</code>. 66170222Sdougb To define the standard names, applications must include the 67170222Sdougb header file 68170222Sdougb <code class="filename"><lwres/netdb.h></code> 69170222Sdougb which contains macro definitions mapping the standard function names 70170222Sdougb into 71170222Sdougb <code class="literal">lwres_</code> 72170222Sdougb prefixed ones. Operating system vendors who integrate the lwres 73170222Sdougb library into their base distributions should rename the functions 74170222Sdougb in the library proper so that the renaming macros are not needed. 75170222Sdougb </p> 76153816Sdougb<p> 77170222Sdougb The library also provides a native API consisting of the functions 78170222Sdougb <code class="function">lwres_getaddrsbyname()</code> 79170222Sdougb and 80170222Sdougb <code class="function">lwres_getnamebyaddr()</code>. 81170222Sdougb These may be called by applications that require more detailed 82170222Sdougb control over the lookup process than the standard functions 83170222Sdougb provide. 84170222Sdougb </p> 85153816Sdougb<p> 86170222Sdougb In addition to these name service independent address lookup 87170222Sdougb functions, the library implements a new, experimental API 88170222Sdougb for looking up arbitrary DNS resource records, using the 89170222Sdougb <code class="function">lwres_getaddrsbyname()</code> 90170222Sdougb function. 91170222Sdougb </p> 92153816Sdougb<p> 93170222Sdougb Finally, there is a low-level API for converting lookup 94170222Sdougb requests and responses to and from raw lwres protocol packets. 95170222Sdougb This API can be used by clients requiring nonblocking operation, 96170222Sdougb and is also used when implementing the server side of the lwres 97170222Sdougb protocol, for example in the 98170222Sdougb <span><strong class="command">lwresd</strong></span> 99170222Sdougb resolver daemon. The use of this low-level API in clients 100170222Sdougb and servers is outlined in the following sections. 101170222Sdougb </p> 102153816Sdougb</div> 103153816Sdougb<div class="refsect1" lang="en"> 104234010Sdougb<a name="id2543427"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2> 105153816Sdougb<p> 106170222Sdougb When a client program wishes to make an lwres request using the 107170222Sdougb native low-level API, it typically performs the following 108170222Sdougb sequence of actions. 109170222Sdougb </p> 110153816Sdougb<p> 111170222Sdougb (1) Allocate or use an existing <span class="type">lwres_packet_t</span>, 112170222Sdougb called <code class="varname">pkt</code> below. 113170222Sdougb </p> 114153816Sdougb<p> 115170222Sdougb (2) Set <em class="structfield"><code>pkt.recvlength</code></em> to the maximum length 116170222Sdougb we will accept. 117170222Sdougb This is done so the receiver of our packets knows how large our receive 118170222Sdougb buffer is. The "default" is a constant in 119170222Sdougb <code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>. 120170222Sdougb </p> 121153816Sdougb<p> 122170222Sdougb (3) Set <em class="structfield"><code>pkt.serial</code></em> 123170222Sdougb to a unique serial number. This value is echoed 124170222Sdougb back to the application by the remote server. 125170222Sdougb </p> 126153816Sdougb<p> 127170222Sdougb (4) Set <em class="structfield"><code>pkt.pktflags</code></em>. Usually this is set to 128170222Sdougb 0. 129170222Sdougb </p> 130153816Sdougb<p> 131170222Sdougb (5) Set <em class="structfield"><code>pkt.result</code></em> to 0. 132170222Sdougb </p> 133153816Sdougb<p> 134170222Sdougb (6) Call <code class="function">lwres_*request_render()</code>, 135170222Sdougb or marshall in the data using the primitives 136170222Sdougb such as <code class="function">lwres_packet_render()</code> 137170222Sdougb and storing the packet data. 138170222Sdougb </p> 139153816Sdougb<p> 140170222Sdougb (7) Transmit the resulting buffer. 141170222Sdougb </p> 142153816Sdougb<p> 143170222Sdougb (8) Call <code class="function">lwres_*response_parse()</code> 144170222Sdougb to parse any packets received. 145170222Sdougb </p> 146153816Sdougb<p> 147170222Sdougb (9) Verify that the opcode and serial match a request, and process the 148170222Sdougb packet specific information contained in the body. 149170222Sdougb </p> 150153816Sdougb</div> 151153816Sdougb<div class="refsect1" lang="en"> 152234010Sdougb<a name="id2543575"></a><h2>SERVER-SIDE LOW-LEVEL API CALL FLOW</h2> 153153816Sdougb<p> 154170222Sdougb When implementing the server side of the lightweight resolver 155170222Sdougb protocol using the lwres library, a sequence of actions like the 156170222Sdougb following is typically involved in processing each request packet. 157170222Sdougb </p> 158153816Sdougb<p> 159170222Sdougb Note that the same <span class="type">lwres_packet_t</span> is used 160170222Sdougb in both the <code class="function">_parse()</code> and <code class="function">_render()</code> calls, 161170222Sdougb with only a few modifications made 162170222Sdougb to the packet header's contents between uses. This method is 163170222Sdougb recommended 164170222Sdougb as it keeps the serial, opcode, and other fields correct. 165170222Sdougb </p> 166153816Sdougb<p> 167170222Sdougb (1) When a packet is received, call <code class="function">lwres_*request_parse()</code> to 168170222Sdougb unmarshall it. This returns a <span class="type">lwres_packet_t</span> (also called <code class="varname">pkt</code>, below) 169170222Sdougb as well as a data specific type, such as <span class="type">lwres_gabnrequest_t</span>. 170170222Sdougb </p> 171153816Sdougb<p> 172170222Sdougb (2) Process the request in the data specific type. 173170222Sdougb </p> 174153816Sdougb<p> 175170222Sdougb (3) Set the <em class="structfield"><code>pkt.result</code></em>, 176170222Sdougb <em class="structfield"><code>pkt.recvlength</code></em> as above. All other fields 177170222Sdougb can 178170222Sdougb be left untouched since they were filled in by the <code class="function">*_parse()</code> call 179170222Sdougb above. If using <code class="function">lwres_*response_render()</code>, 180170222Sdougb <em class="structfield"><code>pkt.pktflags</code></em> will be set up 181170222Sdougb properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be 182170222Sdougb set. 183170222Sdougb </p> 184153816Sdougb<p> 185170222Sdougb (4) Call the data specific rendering function, such as 186170222Sdougb <code class="function">lwres_gabnresponse_render()</code>. 187170222Sdougb </p> 188153816Sdougb<p> 189170222Sdougb (5) Send the resulting packet to the client. 190170222Sdougb </p> 191170222Sdougb<p></p> 192153816Sdougb</div> 193153816Sdougb<div class="refsect1" lang="en"> 194234010Sdougb<a name="id2543658"></a><h2>SEE ALSO</h2> 195170222Sdougb<p><span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>, 196135446Strhodes 197170222Sdougb <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>, 198135446Strhodes 199170222Sdougb <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>, 200135446Strhodes 201170222Sdougb <span class="citerefentry"><span class="refentrytitle">lwres_noop</span>(3)</span>, 202135446Strhodes 203170222Sdougb <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>, 204135446Strhodes 205170222Sdougb <span class="citerefentry"><span class="refentrytitle">lwres_gnba</span>(3)</span>, 206135446Strhodes 207170222Sdougb <span class="citerefentry"><span class="refentrytitle">lwres_context</span>(3)</span>, 208135446Strhodes 209170222Sdougb <span class="citerefentry"><span class="refentrytitle">lwres_config</span>(3)</span>, 210135446Strhodes 211170222Sdougb <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>, 212135446Strhodes 213170222Sdougb <span class="citerefentry"><span class="refentrytitle">lwresd</span>(8)</span>. 214153816Sdougb 215170222Sdougb </p> 216153816Sdougb</div> 217153816Sdougb</div></body> 218153816Sdougb</html> 219