home | help
LWRES(3)			      BIND9				LWRES(3)

NAME
     lwres - introduction to the lightweight resolver library

SYNOPSIS
     #include <lwres/lwres.h>

DESCRIPTION
     The  BIND 9 lightweight resolver library is a simple, name service indepen-
     dent  stub  resolver  library.  It  provides  hostname-to-address	and  ad-
     dress-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 proto-
     col.

OVERVIEW
     The lwresd library implements multiple  name  service  APIs.  The	standard
     gethostbyname(),	gethostbyaddr(),  gethostbyname_r(),  gethostbyaddr_r(),
     getaddrinfo(), getipnodebyname(), 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 integrate the lwres library into  their  base  distribu-
     tions  should rename the functions in the library proper so that the renam-
     ing macros are not needed.

     The library  also	provides  a  native  API  consisting  of  the  functions
     lwres_getaddrsbyname()  and  lwres_getnamebyaddr().  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 re-
     source records, using the lwres_getaddrsbyname() function.

     Finally,  there  is  a low-level API for converting lookup requests and re-
     sponses 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.

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 constant 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  primi-
     tives 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  us-
     ing  the  lwres  library, a sequence of actions like the following is typi-
     cally involved in processing each request packet.

     Note that the same lwres_packet_t is used in both the  _parse()  and  _ren-
     der() calls, with only a few modifications made to the packet header's con-
     tents  between uses. This method is recommended as it keeps the serial, op-
     code, 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_render(), pkt.pktflags will be set up properly.  Oth-
     erwise, the LWRES_LWPACKETFLAG_RESPONSE bit should be set.

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

     (5) Send the resulting packet to the client.

SEE ALSO
     lwres_gethostent(3),	lwres_getipnode(3),	   lwres_getnameinfo(3),
     lwres_noop(3),  lwres_gabn(3),  lwres_gnba(3), lwres_context(3), lwres_con-
     fig(3), resolver(5), lwresd(8).

COPYRIGHT
     Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
     Copyright (C) 2000, 2001 Internet Software Consortium.

BIND9				  Jun 30, 2000				LWRES(3)

home | help