src - FreeBSD source tree

diff options


context:
space:
mode:

author	Doug Barton <dougb@FreeBSD.org>	2007-06-02 23:21:47 +0000
committer	Doug Barton <dougb@FreeBSD.org>	2007-06-02 23:21:47 +0000
commit	141cfa50294bfad08bb6c6419f1dc4fc3165c6ab (patch)
tree	6e65ba28d6d850f4d5c07cd37f26842e97b4aecf /contrib/bind9/lib/lwres/man/lwres.html
parent	fa5fb0343e2347012cf980b8273e2cba6c36de4a (diff)
download	src-141cfa50294bfad08bb6c6419f1dc4fc3165c6ab.tar.gz src-141cfa50294bfad08bb6c6419f1dc4fc3165c6ab.zip

Vendor import of BIND 9.4.1

Notes

Notes: svn path=/vendor/bind9/dist/; revision=170222

Diffstat (limited to 'contrib/bind9/lib/lwres/man/lwres.html')

-rw-r--r--

contrib/bind9/lib/lwres/man/lwres.html

332

1 files changed, 167 insertions, 165 deletions

diff --git a/contrib/bind9/lib/lwres/man/lwres.html b/contrib/bind9/lib/lwres/man/lwres.html
index 02af1f7d98c8..e4bbc098fa16 100644
--- a/contrib/bind9/lib/lwres/man/lwres.html
+++ b/contrib/bind9/lib/lwres/man/lwres.html

@@ -1,5 +1,5 @@

<!--

- Permission to use, copy, modify, and distribute this software for any

@@ -14,15 +14,15 @@

- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR

- PERFORMANCE OF THIS SOFTWARE.

-->

-

+

<html>

<head>

<title>lwres</title>

-<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">

+<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">

</head>

-<a name="id2482688"></a><div class="titlepage"></div>

+<a name="id2476275"></a><div class="titlepage"></div>

lwres — introduction to the lightweight resolver library

@@ -32,185 +32,187 @@

<div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre></div>

</div>

-<a name="id2549397"></a><h2>DESCRIPTION</h2>

-

-The BIND 9 lightweight resolver library is a simple, name service

-independent stub resolver library. It provides hostname-to-address

-and address-to-hostname lookup services to applications by

-transmitting lookup requests to a resolver daemon

-lwresd

-running on the local host. The resover daemon performs the

-lookup using the DNS or possibly other name service protocols,

-and returns the results to the application through the library.

-The library and resolver daemon communicate using a simple

-UDP-based protocol.

-

+<a name="id2543348"></a><h2>DESCRIPTION</h2>

+

+ The BIND 9 lightweight resolver library is a simple, name service

+ independent stub resolver library. It provides hostname-to-address

+ and address-to-hostname lookup services to applications by

+ transmitting lookup requests to a resolver daemon

+ lwresd

+ running on the local host. The resover daemon performs the

+ lookup using the DNS or possibly other name service protocols,

+ and returns the results to the application through the library.

+ The library and resolver daemon communicate using a simple

+ UDP-based protocol.

+

</div>

-<a name="id2549410"></a><h2>OVERVIEW</h2>

-

-The lwresd library implements multiple name service APIs.

-The standard

-<code class="function">gethostbyname()</code>,

-<code class="function">gethostbyaddr()</code>,

-<code class="function">gethostbyname_r()</code>,

-<code class="function">gethostbyaddr_r()</code>,

-<code class="function">getaddrinfo()</code>,

-<code class="function">getipnodebyname()</code>,

-and

-<code class="function">getipnodebyaddr()</code>

-functions are all supported. To allow the lwres library to coexist

-with system libraries that define functions of the same name,

-the library defines these functions with names prefixed by

-<code class="literal">lwres_</code>.

-To define the standard names, applications must include the

-header file

-<code class="filename"><lwres/netdb.h></code>

-which contains macro definitions mapping the standard function names

-into

-<code class="literal">lwres_</code>

-prefixed ones. Operating system vendors who integrate the lwres

-library into their base distributions should rename the functions

-in the library proper so that the renaming macros are not needed.

-

-

-The library also provides a native API consisting of the functions

-<code class="function">lwres_getaddrsbyname()</code>

-and

-<code class="function">lwres_getnamebyaddr()</code>.

-These may be called by applications that require more detailed

-control over the lookup process than the standard functions

-provide.

-

-

-In addition to these name service independent address lookup

-functions, the library implements a new, experimental API

-for looking up arbitrary DNS resource records, using the

-<code class="function">lwres_getaddrsbyname()</code>

-function.

-

-

-Finally, there is a low-level API for converting lookup

-requests and responses to and from raw lwres protocol packets.

-This API can be used by clients requiring nonblocking operation,

-and is also used when implementing the server side of the lwres

-protocol, for example in the

-lwresd

-resolver daemon. The use of this low-level API in clients

-and servers is outlined in the following sections.

-

+<a name="id2543361"></a><h2>OVERVIEW</h2>

+

+ The lwresd library implements multiple name service APIs.

+ The standard

+ <code class="function">gethostbyname()</code>,

+ <code class="function">gethostbyaddr()</code>,

+ <code class="function">gethostbyname_r()</code>,

+ <code class="function">gethostbyaddr_r()</code>,

+ <code class="function">getaddrinfo()</code>,

+ <code class="function">getipnodebyname()</code>,

+ and

+ <code class="function">getipnodebyaddr()</code>

+ functions are all supported. To allow the lwres library to coexist

+ with system libraries that define functions of the same name,

+ the library defines these functions with names prefixed by

+ <code class="literal">lwres_</code>.

+ To define the standard names, applications must include the

+ header file

+ <code class="filename"><lwres/netdb.h></code>

+ which contains macro definitions mapping the standard function names

+ into

+ <code class="literal">lwres_</code>

+ prefixed ones. Operating system vendors who integrate the lwres

+ library into their base distributions should rename the functions

+ in the library proper so that the renaming macros are not needed.

+

+

+ The library also provides a native API consisting of the functions

+ <code class="function">lwres_getaddrsbyname()</code>

+ and

+ <code class="function">lwres_getnamebyaddr()</code>.

+ These may be called by applications that require more detailed

+ control over the lookup process than the standard functions

+ provide.

+

+

+ In addition to these name service independent address lookup

+ functions, the library implements a new, experimental API

+ for looking up arbitrary DNS resource records, using the

+ <code class="function">lwres_getaddrsbyname()</code>

+ function.

+

+

+ Finally, there is a low-level API for converting lookup

+ requests and responses to and from raw lwres protocol packets.

+ This API can be used by clients requiring nonblocking operation,

+ and is also used when implementing the server side of the lwres

+ protocol, for example in the

+ lwresd

+ resolver daemon. The use of this low-level API in clients

+ and servers is outlined in the following sections.

+

</div>

-<a name="id2549474"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2>

-

-When a client program wishes to make an lwres request using the

-native low-level API, it typically performs the following

-sequence of actions.

-

-

-(1) Allocate or use an existing lwres_packet_t,

-called <code class="varname">pkt</code> below.

-

-

-(2) Set <code>pkt.recvlength</code> to the maximum length we will accept.

-This is done so the receiver of our packets knows how large our receive

-buffer is. The "default" is a constant in

-<code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>.

-

-

-(3) Set <code>pkt.serial</code>

-to a unique serial number. This value is echoed

-back to the application by the remote server.

-

-

-(4) Set <code>pkt.pktflags</code>. Usually this is set to 0.

-

-

-(5) Set <code>pkt.result</code> to 0.

-

-

-(6) Call <code class="function">lwres_*request_render()</code>,

-or marshall in the data using the primitives

-such as <code class="function">lwres_packet_render()</code>

-and storing the packet data.

-

-

-(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.

-

+<a name="id2543425"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2>

+

+ When a client program wishes to make an lwres request using the

+ native low-level API, it typically performs the following

+ sequence of actions.

+

+

+ (1) Allocate or use an existing lwres_packet_t,

+ called <code class="varname">pkt</code> below.

+

+

+ (2) Set <code>pkt.recvlength</code> to the maximum length

+ we will accept.

+ This is done so the receiver of our packets knows how large our receive

+ buffer is. The "default" is a constant in

+ <code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>.

+

+

+ (3) Set <code>pkt.serial</code>

+ to a unique serial number. This value is echoed

+ back to the application by the remote server.

+

+

+ (4) Set <code>pkt.pktflags</code>. Usually this is set to

+ 0.

+

+

+ (5) Set <code>pkt.result</code> to 0.

+

+

+ (6) Call <code class="function">lwres_*request_render()</code>,

+ or marshall in the data using the primitives

+ such as <code class="function">lwres_packet_render()</code>

+ and storing the packet data.

+

+

+ (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>

-<a name="id2549689"></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 lwres_packet_t 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 recommended

-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 lwres_packet_t (also called <code class="varname">pkt</code>, below)

-as well as a data specific type, such as lwres_gabnrequest_t.

-

-

-(2) Process the request in the data specific type.

-

-

-(3) Set the <code>pkt.result</code>,

-<code>pkt.recvlength</code> as above. All other fields can

-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>,

-<code>pkt.pktflags</code> will be set up

-properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be

-set.

-

-

-(4) Call the data specific rendering function, such as

-<code class="function">lwres_gabnresponse_render()</code>.

-

-

-(5) Send the resulting packet to the client.

-

-

-

+<a name="id2543573"></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 lwres_packet_t 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

+ recommended

+ 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 lwres_packet_t (also called <code class="varname">pkt</code>, below)

+ as well as a data specific type, such as lwres_gabnrequest_t.

+

+

+ (2) Process the request in the data specific type.

+

+

+ (3) Set the <code>pkt.result</code>,

+ <code>pkt.recvlength</code> as above. All other fields

+ can

+ 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>,

+ <code>pkt.pktflags</code> will be set up

+ properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be

+ set.

+

+

+ (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>

-<a name="id2549774"></a><h2>SEE ALSO</h2>

-

-lwres_gethostent(3),

+<a name="id2543656"></a><h2>SEE ALSO</h2>

+lwres_gethostent(3),

-lwres_getipnode(3),

+ lwres_getipnode(3),

-lwres_getnameinfo(3),

+ lwres_getnameinfo(3),

-lwres_noop(3),

+ lwres_noop(3),

-lwres_gabn(3),

+ lwres_gabn(3),

-lwres_gnba(3),

+ lwres_gnba(3),

-lwres_context(3),

+ lwres_context(3),

-lwres_config(3),

+ lwres_config(3),

-resolver(5),

+ resolver(5),

-lwresd(8).

+ lwresd(8).

-

+

</div>

</div></body>

</html>