10139N/A - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC") 10139N/A - Copyright (C) 2000, 2001 Internet Software Consortium. 10139N/A - Permission to use, copy, modify, and/or distribute this software for any 10139N/A - purpose with or without fee is hereby granted, provided that the above 10139N/A - copyright notice and this permission notice appear in all copies. 10139N/A - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10139N/A - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 10139N/A - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 10139N/A - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 10139N/A - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 13612N/A - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 12067N/A - PERFORMANCE OF THIS SOFTWARE. 13322N/A<
meta http-
equiv="Content-Type" content="text/html; charset=ISO-8859-1">
12070N/A<
meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
10139N/A<
body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><
div class="refentry" title="lwres">
10139N/A<
a name="idp60840656"></
a><
div class="titlepage"></
div>
10139N/A — introduction to the lightweight resolver library
10139N/A <
div class="refsynopsisdiv" title="Synopsis">
10139N/A <
div class="refsection" title="DESCRIPTION">
10139N/A<
a name="idp60883920"></
a><
h2>DESCRIPTION</
h2>
10139N/A The BIND 9 lightweight resolver library is a simple, name service
10139N/A independent stub resolver library. It provides hostname-to-address
10139N/A and address-to-hostname lookup services to applications by
10139N/A transmitting lookup requests to a resolver daemon
10139N/A <
span class="command"><
strong>lwresd</
strong></
span>
10139N/A running on the local host. The resolver daemon performs the
10139N/A lookup using the DNS or possibly other name service protocols,
10139N/A and returns the results to the application through the library.
10139N/A The library and resolver daemon communicate using a simple
10139N/A <
div class="refsection" title="OVERVIEW">
10139N/A<
a name="idp60885712"></
a><
h2>OVERVIEW</
h2>
10139N/A The lwresd library implements multiple name service APIs.
10139N/A <
code class="function">gethostbyname()</
code>,
10139N/A <
code class="function">gethostbyaddr()</
code>,
10139N/A <
code class="function">gethostbyname_r()</
code>,
10139N/A <
code class="function">gethostbyaddr_r()</
code>,
10139N/A <
code class="function">getaddrinfo()</
code>,
10139N/A <
code class="function">getipnodebyname()</
code>,
13612N/A <
code class="function">getipnodebyaddr()</
code>
13612N/A functions are all supported. To allow the lwres library to coexist
13322N/A with system libraries that define functions of the same name,
13322N/A the library defines these functions with names prefixed by
12451N/A <
code class="literal">lwres_</
code>.
12451N/A To define the standard names, applications must include the
12070N/A which contains macro definitions mapping the standard function names
12067N/A <
code class="literal">lwres_</
code>
12067N/A prefixed ones. Operating system vendors who integrate the lwres
12020N/A library into their base distributions should rename the functions
12020N/A in the library proper so that the renaming macros are not needed.
11139N/A The library also provides a native API consisting of the functions
11139N/A <
code class="function">lwres_getaddrsbyname()</
code>
11132N/A <
code class="function">lwres_getnamebyaddr()</
code>.
11132N/A These may be called by applications that require more detailed
11013N/A control over the lookup process than the standard functions
11010N/A In addition to these name service independent address lookup
10467N/A functions, the library implements a new, experimental API
11010N/A for looking up arbitrary DNS resource records, using the
11010N/A <
code class="function">lwres_getaddrsbyname()</
code>
11139N/A Finally, there is a low-level API for converting lookup
11139N/A requests and responses to and from raw lwres protocol packets.
10139N/A This API can be used by clients requiring nonblocking operation,
10139N/A and is also used when implementing the server side of the lwres
10139N/A <
span class="command"><
strong>lwresd</
strong></
span>
10139N/A resolver daemon. The use of this low-level API in clients
10139N/A and servers is outlined in the following sections.
10139N/A <
div class="refsection" title="CLIENT-SIDE LOW-LEVEL API CALL FLOW">
10139N/A<
a name="idp60898000"></
a><
h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</
h2>
10139N/A When a client program wishes to make an lwres request using the
10139N/A native low-level API, it typically performs the following
10139N/A (1) Allocate or use an existing <
span class="type">lwres_packet_t</
span>,
10139N/A called <
code class="varname">pkt</
code> below.
10139N/A This is done so the receiver of our packets knows how large our receive
10139N/A buffer is. The "default" is a constant in
10139N/A <
code class="filename">
lwres.h</
code>: <
code class="constant">LWRES_RECVLENGTH = 4096</
code>.
10139N/A to a unique serial number. This value is echoed
10139N/A back to the application by the remote server.
10139N/A (6) Call <
code class="function">lwres_*request_render()</
code>,
10139N/A or marshall in the data using the primitives
10139N/A such as <
code class="function">lwres_packet_render()</
code>
(7) Transmit the resulting buffer.
(8) Call <
code class="function">lwres_*response_parse()</
code>
to parse any packets received.
(9) Verify that the opcode and serial match a request, and process the
packet specific information contained in the body.
<
div class="refsection" title="SERVER-SIDE LOW-LEVEL API CALL FLOW">
<
a name="idp60907856"></
a><
h2>SERVER-SIDE LOW-LEVEL API CALL FLOW</
h2>
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.
Note that the same <
span class="type">lwres_packet_t</
span> is used
in both the <
code class="function">_parse()</
code> and <
code class="function">_render()</
code> calls,
with only a few modifications made
to the packet header's contents between uses. This method is
as it keeps the serial, opcode, and other fields correct.
(1) When a packet is received, call <
code class="function">lwres_*request_parse()</
code> to
unmarshall it. This returns a <
span class="type">lwres_packet_t</
span> (also called <
code class="varname">pkt</
code>, below)
as well as a data specific type, such as <
span class="type">lwres_gabnrequest_t</
span>.
(2) Process the request in the data specific type.
(3) Set the <
code class="varname">
pkt.result</
code>,
<
code class="varname">
pkt.recvlength</
code> as above. All other fields
be left untouched since they were filled in by the <
code class="function">*_parse()</
code> call
above. If using <
code class="function">lwres_*response_render()</
code>,
properly. Otherwise, the <
code class="constant">LWRES_LWPACKETFLAG_RESPONSE</
code> bit should be
(4) Call the data specific rendering function, such as
<
code class="function">lwres_gabnresponse_render()</
code>.
(5) Send the resulting packet to the client.
<
div class="refsection" title="SEE ALSO">
<
a name="idp60926032"></
a><
h2>SEE ALSO</
h2>
<
p><
span class="citerefentry">
<
span class="refentrytitle">lwres_gethostent</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">lwres_getipnode</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">lwres_getnameinfo</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">lwres_noop</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">lwres_gabn</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">lwres_gnba</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">lwres_context</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">lwres_config</
span>(3)
<
span class="citerefentry">
<
span class="refentrytitle">resolver</
span>(5)
<
span class="citerefentry">
<
span class="refentrytitle">lwresd</
span>(8)