LWRES(3)LWRES(3)NAMElwres - introduction to the lightweight resolver library
SYNOPSIS
#include <lwres/lwres.h>
DESCRIPTION
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 ser-
vices 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 possi-
bly 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 pro-
tocol.
OVERVIEW
The lwresd library implements multiple name service APIs.
The standard gethostbyname(), gethostbyaddr(), gethostby-
name_r(), gethostbyaddr_r(), getaddrinfo(), getipnodeby-
name(), and getipnodebyaddr() 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
lwres_. To define the standard names, applications must
include the header file <lwres/netdb.h> which contains
macro definitions mapping the standard function names into
lwres_ prefixed ones. Operating system vendors who inte-
grate 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 lwres_getaddrsbyname() and lwres_getname-
byaddr(). 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, experimen-
tal API for looking up arbitrary DNS resource records,
using the lwres_getaddrsbyname() 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 non-
blocking 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.
CLIENT-SIDE LOW-LEVEL API CALL FLOW
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 pkt
below.
(2) Set pkt.recvlength 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 con-
stant in lwres.h: LWRES_RECVLENGTH = 4096.
(3) Set pkt.serial to a unique serial number. This value
is echoed back to the application by the remote server.
(4) Set pkt.pktflags. Usually this is set to 0.
(5) Set pkt.result to 0.
(6) Call lwres_*request_render(), or marshall in the data
using the primitives such as lwres_packet_render() and
storing the packet data.
(7) Transmit the resulting buffer.
(8) Call lwres_*response_parse() 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.
SERVER-SIDE LOW-LEVEL API CALL FLOW
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 pro-
cessing each request packet.
Note that the same lwres_packet_t is used in both the
_parse() and _render() calls, with only a few modifica-
tions 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 lwres_*request_parse()
to unmarshall it. This returns a lwres_packet_t (also
called pkt, 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 pkt.result, pkt.recvlength as above. All other
fields can be left untouched since they were filled in by
the *_parse() call above. If using lwres_*response_ren-
der(), pkt.pktflags will be set up properly. Otherwise,
the LWRES_LWPACKETFLAG_RESPONSE bit should be set.
(4) Call the data specific rendering function, such as
lwres_gabnresponse_render().
(5) Send the resulting packet to the client.
SEE ALSOlwres_gethostent(3), lwres_getipnode(3), lwres_getname-
info(3), lwres_noop(3), lwres_gabn(3), lwres_gnba(3),
lwres_context(3), lwres_config(3), resolver(5), lwresd(8).
BIND9 Jun 30, 2000 LWRES(3)
