12739N/A<!
DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 12739N/A - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC") 12739N/A - Copyright (C) 2000, 2001 Internet Software Consortium. 12739N/A - Permission to use, copy, modify, and/or distribute this software for any 12739N/A - purpose with or without fee is hereby granted, provided that the above 12739N/A - copyright notice and this permission notice appear in all copies. 12739N/A - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 12739N/A - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 12739N/A - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12739N/A - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 12739N/A - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 12739N/A - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 12739N/A - PERFORMANCE OF THIS SOFTWARE. 12739N/A <
refentrytitle>lwres</
refentrytitle>
12739N/A <
refmiscinfo>BIND9</
refmiscinfo>
12739N/A <
refpurpose>introduction to the lightweight resolver library</
refpurpose>
12739N/A <
holder>Internet Systems Consortium, Inc. ("ISC")</
holder>
12739N/A <
holder>Internet Software Consortium.</
holder>
12739N/A The BIND 9 lightweight resolver library is a simple, name service
12739N/A independent stub resolver library. It provides hostname-to-address
12739N/A and address-to-hostname lookup services to applications by
12739N/A transmitting lookup requests to a resolver daemon
12739N/A running on the local host. The resolver daemon performs the
12739N/A lookup using the DNS or possibly other name service protocols,
12739N/A and returns the results to the application through the library.
12739N/A The library and resolver daemon communicate using a simple
12739N/A The lwresd library implements multiple name service APIs.
12739N/A <
function>gethostbyname()</
function>,
12739N/A <
function>gethostbyaddr()</
function>,
12739N/A <
function>gethostbyname_r()</
function>,
12739N/A <
function>gethostbyaddr_r()</
function>,
12739N/A <
function>getaddrinfo()</
function>,
12739N/A <
function>getipnodebyname()</
function>,
12739N/A <
function>getipnodebyaddr()</
function>
12739N/A functions are all supported. To allow the lwres library to coexist
12739N/A with system libraries that define functions of the same name,
12739N/A the library defines these functions with names prefixed by
12739N/A To define the standard names, applications must include the
12739N/A which contains macro definitions mapping the standard function names
12739N/A prefixed ones. Operating system vendors who integrate the lwres
12739N/A library into their base distributions should rename the functions
12739N/A in the library proper so that the renaming macros are not needed.
12739N/A The library also provides a native API consisting of the functions
12739N/A <
function>lwres_getaddrsbyname()</
function>
12739N/A <
function>lwres_getnamebyaddr()</
function>.
12739N/A These may be called by applications that require more detailed
12739N/A control over the lookup process than the standard functions
12739N/A In addition to these name service independent address lookup
12739N/A functions, the library implements a new, experimental API
12739N/A for looking up arbitrary DNS resource records, using the
12739N/A <
function>lwres_getaddrsbyname()</
function>
12739N/A Finally, there is a low-level API for converting lookup
12739N/A requests and responses to and from raw lwres protocol packets.
12739N/A This API can be used by clients requiring nonblocking operation,
12739N/A and is also used when implementing the server side of the lwres
12739N/A resolver daemon. The use of this low-level API in clients
12739N/A and servers is outlined in the following sections.
12739N/A <
title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</
title>
12739N/A When a client program wishes to make an lwres request using the
12739N/A native low-level API, it typically performs the following
12739N/A (1) Allocate or use an existing <
type>lwres_packet_t</
type>,
12739N/A called <
varname>pkt</
varname> below.
12739N/A This is done so the receiver of our packets knows how large our receive
12739N/A buffer is. The "default" is a constant in
12739N/A <
filename>
lwres.h</
filename>: <
constant>LWRES_RECVLENGTH = 4096</
constant>.
12739N/A to a unique serial number. This value is echoed
12739N/A back to the application by the remote server.
12739N/A (6) Call <
function>lwres_*request_render()</
function>,
12739N/A or marshall in the data using the primitives
12739N/A such as <
function>lwres_packet_render()</
function>
12739N/A (7) Transmit the resulting buffer.
12739N/A (8) Call <
function>lwres_*response_parse()</
function>
12739N/A (9) Verify that the opcode and serial match a request, and process the
12739N/A packet specific information contained in the body.
12739N/A <
title>SERVER-SIDE LOW-LEVEL API CALL FLOW</
title>
12739N/A When implementing the server side of the lightweight resolver
12739N/A protocol using the lwres library, a sequence of actions like the
12739N/A following is typically involved in processing each request packet.
12739N/A Note that the same <
type>lwres_packet_t</
type> is used
12739N/A in both the <
function>_parse()</
function> and <
function>_render()</
function> calls,
12739N/A with only a few modifications made
12739N/A to the packet header's contents between uses. This method is
12739N/A as it keeps the serial, opcode, and other fields correct.
12739N/A (1) When a packet is received, call <
function>lwres_*request_parse()</
function> to
12739N/A unmarshall it. This returns a <
type>lwres_packet_t</
type> (also called <
varname>pkt</
varname>, below)
12739N/A as well as a data specific type, such as <
type>lwres_gabnrequest_t</
type>.
12739N/A (2) Process the request in the data specific type.
12739N/A be left untouched since they were filled in by the <
function>*_parse()</
function> call
12739N/A above. If using <
function>lwres_*response_render()</
function>,
12739N/A properly. Otherwise, the <
constant>LWRES_LWPACKETFLAG_RESPONSE</
constant> bit should be
12739N/A (4) Call the data specific rendering function, such as
12739N/A <
function>lwres_gabnresponse_render()</
function>.
12739N/A (5) Send the resulting packet to the client.
12739N/A <
refentrytitle>lwres_gethostent</
refentrytitle><
manvolnum>3</
manvolnum>
12739N/A <
refentrytitle>lwres_getipnode</
refentrytitle><
manvolnum>3</
manvolnum>
12840N/A <
refentrytitle>lwres_getnameinfo</
refentrytitle><
manvolnum>3</
manvolnum>
12840N/A <
refentrytitle>lwres_noop</
refentrytitle><
manvolnum>3</
manvolnum>
12840N/A <
refentrytitle>lwres_gabn</
refentrytitle><
manvolnum>3</
manvolnum>
12840N/A <
refentrytitle>lwres_gnba</
refentrytitle><
manvolnum>3</
manvolnum>
12739N/A <
refentrytitle>lwres_context</
refentrytitle><
manvolnum>3</
manvolnum>
12739N/A <
refentrytitle>lwres_config</
refentrytitle><
manvolnum>3</
manvolnum>
12739N/A <
refentrytitle>resolver</
refentrytitle><
manvolnum>5</
manvolnum>
12739N/A <
refentrytitle>lwresd</
refentrytitle><
manvolnum>8</
manvolnum>