lwres.html revision 010a51c427bfb6ab658fc0056955a1a5b69810be
205c10066a0acfeac52d1a135671f41d207b8557Automatic Updater - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
205c10066a0acfeac52d1a135671f41d207b8557Automatic Updater - Copyright (C) 2000, 2001 Internet Software Consortium.
0c39b3ed9409ecb277d5e32fa763a4e4d6598df8Automatic Updater - Permission to use, copy, modify, and/or distribute this software for any
2bb3422dc683c013db7042f5736240de6b86f182Automatic Updater - purpose with or without fee is hereby granted, provided that the above
cd0aa2d941d1438fabb5337f1f38c49478edf71dAutomatic Updater - copyright notice and this permission notice appear in all copies.
ea854b585041ad19f70f7af15e08144ef2c2bd1bMark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
78cb74fab4665da2e2641ba909c6f59f74cc4193Automatic Updater - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
cd0aa2d941d1438fabb5337f1f38c49478edf71dAutomatic Updater - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
90ff38a0d8deaf5f9c2aa5916d99b2e572d28738Automatic Updater - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
6c6a121295b30772cbf3dd75a51fb9d883051a0eAutomatic Updater - PERFORMANCE OF THIS SOFTWARE.
56874aef380a64a2c183b7c282c3e7a361d67fa1Automatic Updater<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
96713299d08c0735c18ebe8772dd2cc1ecd4356aAutomatic Updater<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" title="lwres">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<a name="idp60693712"></a><div class="titlepage"></div>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater — introduction to the lightweight resolver library
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <div class="refsynopsisdiv" title="Synopsis">
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
2d2dc37599979c83495510f8af8d1756753aa2c5Automatic Updater <div class="refsection" title="DESCRIPTION">
2d2dc37599979c83495510f8af8d1756753aa2c5Automatic Updater<a name="idp60737360"></a><h2>DESCRIPTION</h2>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater The BIND 9 lightweight resolver library is a simple, name service
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater independent stub resolver library. It provides hostname-to-address
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater and address-to-hostname lookup services to applications by
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater transmitting lookup requests to a resolver daemon
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater <span class="command"><strong>lwresd</strong></span>
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater running on the local host. The resolver daemon performs the
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater lookup using the DNS or possibly other name service protocols,
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater and returns the results to the application through the library.
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater The library and resolver daemon communicate using a simple
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater UDP-based protocol.
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater<a name="idp60739152"></a><h2>OVERVIEW</h2>
80faf1588895fd26490f82f95a7a1b771df1c324Automatic Updater The lwresd library implements multiple name service APIs.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews The standard
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater <code class="function">gethostbyname()</code>,
db5b7e2cdf150c46e8242d3e2e3ad3f5c7300258Automatic Updater <code class="function">gethostbyname_r()</code>,
80faf1588895fd26490f82f95a7a1b771df1c324Automatic Updater <code class="function">gethostbyaddr_r()</code>,
1a06700908f5a1d9f4a8d51285a0fd971e2f9117Automatic Updater <code class="function">getipnodebyname()</code>,
db5b7e2cdf150c46e8242d3e2e3ad3f5c7300258Automatic Updater <code class="function">getipnodebyaddr()</code>
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews functions are all supported. To allow the lwres library to coexist
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews with system libraries that define functions of the same name,
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater the library defines these functions with names prefixed by
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater To define the standard names, applications must include the
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews <code class="filename"><lwres/netdb.h></code>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater which contains macro definitions mapping the standard function names
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater prefixed ones. Operating system vendors who integrate the lwres
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson library into their base distributions should rename the functions
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater in the library proper so that the renaming macros are not needed.
9174e44c14b1cb91a651fa1dc29470438c246ab9Automatic Updater The library also provides a native API consisting of the functions
b1265b5a06df36d490d4bdf54284fb133a1f5a84Automatic Updater <code class="function">lwres_getaddrsbyname()</code>
9174e44c14b1cb91a651fa1dc29470438c246ab9Automatic Updater <code class="function">lwres_getnamebyaddr()</code>.
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont These may be called by applications that require more detailed
0c39b3ed9409ecb277d5e32fa763a4e4d6598df8Automatic Updater control over the lookup process than the standard functions
f9119ad8f6114b2255e7545bf5cd187f4db0a89bAutomatic Updater In addition to these name service independent address lookup
9174e44c14b1cb91a651fa1dc29470438c246ab9Automatic Updater functions, the library implements a new, experimental API
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews for looking up arbitrary DNS resource records, using the
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater <code class="function">lwres_getaddrsbyname()</code>
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater Finally, there is a low-level API for converting lookup
b29e5c56eb74a6de1a84c29879afc90ffc6b1436Automatic Updater requests and responses to and from raw lwres protocol packets.
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater This API can be used by clients requiring nonblocking operation,
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater and is also used when implementing the server side of the lwres
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews protocol, for example in the
0977f3f39ef6728516be7976452b9122c8f5607aAutomatic Updater <span class="command"><strong>lwresd</strong></span>
ae7e54b14c946e0984c191554db9abb4893f9349Automatic Updater resolver daemon. The use of this low-level API in clients
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews and servers is outlined in the following sections.
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater <div class="refsection" title="CLIENT-SIDE LOW-LEVEL API CALL FLOW">
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater<a name="idp60751440"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater When a client program wishes to make an lwres request using the
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater native low-level API, it typically performs the following
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater sequence of actions.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson (1) Allocate or use an existing <span class="type">lwres_packet_t</span>,
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater called <code class="varname">pkt</code> below.
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater (2) Set <code class="varname">pkt.recvlength</code> to the maximum length
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater we will accept.
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater This is done so the receiver of our packets knows how large our receive
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater buffer is. The "default" is a constant in
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater <code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson (3) Set <code class="varname">pkt.serial</code>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater to a unique serial number. This value is echoed
4104e236f71eb5108fcfda6711878a97f6f4a8e7Automatic Updater back to the application by the remote server.
0ce87e5749aabb8eef1e0a37e4bd6e6ffa1d7196Automatic Updater (4) Set <code class="varname">pkt.pktflags</code>. Usually this is set to
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater (5) Set <code class="varname">pkt.result</code> to 0.
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater (6) Call <code class="function">lwres_*request_render()</code>,
d145b64cacc8d9cda51f9924ec70cd4661c3e2cfAutomatic Updater or marshall in the data using the primitives
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater such as <code class="function">lwres_packet_render()</code>
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater and storing the packet data.
0df8ead472f207020f8da22a185fe4b945248ab8Automatic Updater (7) Transmit the resulting buffer.
bc0a53583d92309bebcf93c408e2f3247ebd3d3cAutomatic Updater (8) Call <code class="function">lwres_*response_parse()</code>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater to parse any packets received.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater (9) Verify that the opcode and serial match a request, and process the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater packet specific information contained in the body.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <div class="refsection" title="SERVER-SIDE LOW-LEVEL API CALL FLOW">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="idp60769616"></a><h2>SERVER-SIDE LOW-LEVEL API CALL FLOW</h2>
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater When implementing the server side of the lightweight resolver
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater protocol using the lwres library, a sequence of actions like the
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater following is typically involved in processing each request packet.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Note that the same <span class="type">lwres_packet_t</span> is used
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater in both the <code class="function">_parse()</code> and <code class="function">_render()</code> calls,
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater with only a few modifications made
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater to the packet header's contents between uses. This method is
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater as it keeps the serial, opcode, and other fields correct.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater (1) When a packet is received, call <code class="function">lwres_*request_parse()</code> to
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater unmarshall it. This returns a <span class="type">lwres_packet_t</span> (also called <code class="varname">pkt</code>, below)
bbb069be941f649228760edcc241122933c066d2Automatic Updater as well as a data specific type, such as <span class="type">lwres_gabnrequest_t</span>.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews (2) Process the request in the data specific type.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews (3) Set the <code class="varname">pkt.result</code>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="varname">pkt.recvlength</code> as above. All other fields
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews be left untouched since they were filled in by the <code class="function">*_parse()</code> call
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews above. If using <code class="function">lwres_*response_render()</code>,
70f5a54bf2676b136aa838d1ee9688e00b5dd8b9Automatic Updater <code class="varname">pkt.pktflags</code> will be set up
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be
bc0a53583d92309bebcf93c408e2f3247ebd3d3cAutomatic Updater (4) Call the data specific rendering function, such as
b109432c3a939bff66a463be86c371bd88efe3aaAutomatic Updater <code class="function">lwres_gabnresponse_render()</code>.
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater (5) Send the resulting packet to the client.
96713299d08c0735c18ebe8772dd2cc1ecd4356aAutomatic Updater<a name="idp60779472"></a><h2>SEE ALSO</h2>
cf7e98f59148b559946a7f1ca728471374f1eef3Automatic Updater <span class="refentrytitle">lwres_gethostent</span>(3)
361bec4bdec45042897fb479b7071cd05bbd56b9Automatic Updater <span class="refentrytitle">lwres_getipnode</span>(3)
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="refentrytitle">lwres_getnameinfo</span>(3)
80faf1588895fd26490f82f95a7a1b771df1c324Automatic Updater <span class="refentrytitle">lwres_noop</span>(3)
e2caa7536302de34de6cc04025abcd53dc3a499aAutomatic Updater <span class="refentrytitle">lwres_gabn</span>(3)
7d12a6b412fe47e6d6582923fd6954ab8cd0baebAutomatic Updater <span class="refentrytitle">lwres_gnba</span>(3)
ca35524ce2b57e6f1b261d23565d1288a355d12fAutomatic Updater <span class="refentrytitle">lwres_context</span>(3)
7d12a6b412fe47e6d6582923fd6954ab8cd0baebAutomatic Updater <span class="refentrytitle">lwres_config</span>(3)
7d12a6b412fe47e6d6582923fd6954ab8cd0baebAutomatic Updater <span class="refentrytitle">resolver</span>(5)
7d12a6b412fe47e6d6582923fd6954ab8cd0baebAutomatic Updater <span class="refentrytitle">lwresd</span>(8)