diff --git a/doc/man/lwres/lwres_buffer.3 b/doc/man/lwres/lwres_buffer.3
index ec69ae6c87..172d0ba10e 100644
--- a/doc/man/lwres/lwres_buffer.3
+++ b/doc/man/lwres/lwres_buffer.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_buffer.3,v 1.3 2000/08/01 01:20:26 tale Exp $
+.\" $Id: lwres_buffer.3,v 1.4 2000/09/28 22:36:23 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_BUFFER 3
@@ -118,24 +118,13 @@
 .Fa "unsigned int length"
 .Fc
 .Sh DESCRIPTION
-These functions use the following structure as a buffer descriptor to
-manage the actual storage:
-.Bd -literal -offset indent
-typedef struct lwres_buffer lwres_buffer_t;
-struct lwres_buffer {
-	unsigned int		magic;
-	unsigned char 	       *base;
-	/* The following integers are byte offsets from 'base'. */
-	unsigned int		length;
-	unsigned int		used;
-	unsigned int 		current;
-	unsigned int 		active;
-};
-.Ed
-The main reason for making the buffer structure public is so that
-buffer operations can be implemented using macros.
-Applications should not manipulate this structure directly.
-They should use the functions listed below.
+
+
+These functions provide bounds checked access to a region of memory
+where data is being read or written.
+They are based on, and similar to, the
+.Va isc_buffer_
+functions in the ISC library.
 .Pp
 A buffer is a region of memory, together with a set of related
 subregions.
@@ -168,33 +157,42 @@ Initially, the active region is empty.
 If the current offset advances beyond the chosen offset,
 the active region will also be empty.
 .Pp
-Except for
-.Fn lwres_buffer_init ,
-all of the buffer managements functions contain an assertion check
-that
-.Fa b
-is a pointer to a valid lightweight resolver buffer.
+.Bd -literal -offset indent
+ 
+   /------------entire length---------------\\
+   /----- used region -----\\/-- available --\\
+   +----------------------------------------+
+   | consumed  | remaining |                |
+   +----------------------------------------+
+   a           b     c     d                e
+ 
+  a == base of buffer.
+  b == current pointer.  Can be anywhere between a and d.
+  c == active pointer.  Meaningful between b and d.
+  d == used pointer.
+  e == length of buffer.
+ 
+  a-e == entire length of buffer.
+  a-d == used region.
+  a-b == consumed region.
+  b-d == remaining region.
+  b-c == optional active region.
+.Ed
 .Pp
 .Fn lwres_buffer_init
-makes the
-.Dv "struct lwres_buffer"
-referenced by
+initializes the
+.Dv lwres_buffer_t
 .Fa *b
-to be associated with a memory region of size
+and assocates it with the memory region of size
 .Fa length
 bytes starting at location
 .Fa base.
-The function checks that
-.Fa *b is not
-.Dv NULL .
 .Pp
-The
-.Dv lwres_buffer_t
-.Fa *b
-is invalidated by
-.Fn lwres_buffer_invalidate .
-.Fa *b
-must be a valid lightweight resolver buffer.
+.Fn lwres_buffer_invalidate
+marks the buffer
+.Fa *b 
+as invalid.  Invalidating a buffer after use is not required,
+but makes it possible to catch its possible accidental use.
 .Pp
 The functions
 .Fn lwres_buffer_add
@@ -206,70 +204,62 @@ buffer
 by
 .Fa n
 bytes.
-.Fa *b
 .Fn lwres_buffer_add
 checks for buffer overflow and
 .Fn lwres_buffer_subtract
 checks for underflow.
 These functions do not allocate or deallocate memory.
 They just change the value of
-.Li b->used .
+.Li used .
 .Pp
-A lightweight resolver buffer is re-initialised by
+A buffer is re-initialised by
 .Fn lwres_buffer_clear .
 The function sets
-.Li b->used ,
-.Li b->current
+.Li used ,
+.Li current
 and
-.Li b->active
+.Li active
 to zero.
 .Pp
 .Fn lwres_buffer_first
 makes the consumed region of buffer
 .Fa *p
 empty by setting
-.Li b->current
-to zero: the start of the buffer.
+.Li current
+to zero (the start of the buffer).
 .Pp
-The consumed region of buffer
+.Fn lwres_buffer_forward 
+increases the consumed region of buffer
 .Fa *b
-is increased by
+by
 .Fa n
-bytes
-using
-.Fn lwres_buffer_forward .
-The function checks for buffer overflow.
+bytes, checking for overflow.
 Similarly,
 .Fn lwres_buffer_back
 decreases buffer
 .Fa b 's
 consumed region by
 .Fa n
-bytes and checks for buffer underflow.
+bytes and checks for underflow.
 .Pp
 .Fn lwres_buffer_getuint8
 reads an unsigned 8-bit integer from
 .Fa *b
 and returns it.
-The function checks that it does not read past the end of the buffer's
-consumed region.
 .Fn lwres_buffer_putuint8
 writes the unsigned 8-bit integer
 .Fa val
 to buffer
 .Fa *b .
-It checks that the buffer has available space for
-.Fa val .
 .Pp
 .Fn lwres_buffer_getuint16
 and
 .Fn lwres_buffer_getuint32
 are identical to
 .Fn lwres_buffer_putuint8
-except that they respectively read an unsigned 16-bit or 32-bit integer from
-.Fa b
-converting it from network byte order to host byte order before
-returning its value.
+except that they respectively read an unsigned 16-bit or 32-bit integer 
+in network byte order from
+.Fa b .
 Similarly,
 .Fn lwres_buffer_putuint16
 and
@@ -278,7 +268,7 @@ writes the unsigned 16-bit or 32-bit integer
 .Fa val
 to buffer
 .Fa b ,
-converting it from host byte order to network byte order.
+in network byte order.
 .Pp
 Arbitrary amounts of data are read or written from a lightweight
 resolver buffer with
@@ -301,23 +291,4 @@ bytes of memory from
 .Fa b
 to
 .Fa base .
-For both functions,
-.Fa base
-should point to at least
-.Fa length
-bytes of valid memory.
-.Fa base
-.Sh RETURN VALUES
-.Fn lwres_buffer_getuint8 ,
-.Fn lwres_buffer_getuint16
-and
-.Fn lwres_buffer_getuint32
-return an 8-, 16- or 32-bit unsigned integer respectively from the
-current offset in buffer
-.Fa b .
-The 16- and 32-bit quantities are presented in host byte order even
-though they are stored in network byte order inside the buffer.
 .Sh SEE ALSO
-.Sh BUGS
-Buffers have no synchronization.
-Clients must ensure exclusive access for thread-safe operations.
diff --git a/doc/man/lwres/lwres_context.3 b/doc/man/lwres/lwres_context.3
index 2ae8205992..5e3019a840 100644
--- a/doc/man/lwres/lwres_context.3
+++ b/doc/man/lwres/lwres_context.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_context.3,v 1.3 2000/08/01 01:20:52 tale Exp $
+.\" $Id: lwres_context.3,v 1.4 2000/09/28 22:36:24 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_CONTEXT 3
@@ -27,7 +27,7 @@
 .Nm lwres_context_freemem ,
 .Nm lwres_context_allocmem ,
 .Nm lwres_context_sendrecv
-.Nd lightweight resolver memory allocation routines
+.Nd lightweight resolver context management
 .Sh SYNOPSIS
 .Fd #include <lwres/lwres.h>
 .Fd
@@ -43,14 +43,14 @@
 .Fa "lwres_context_t **contextp"
 .Fc
 .Ft void
-.Fo lwres_context_nextserial
-.Fa "lwres_context_t *ctx"
-.Fc
-.Ft lwres_uint32_t
 .Fo lwres_context_initserial
 .Fa "lwres_context_t *ctx"
 .Fa "lwres_uint32_t serial"
 .Fc
+.Ft lwres_uint32_t
+.Fo lwres_context_nextserial
+.Fa "lwres_context_t *ctx"
+.Fc
 .Ft void
 .Fo lwres_context_freemem
 .Fa "lwres_context_t *ctx"
@@ -71,95 +71,81 @@
 .Fa "int recvlen"
 .Fa "int *recvd_len"
 .Fc
-.Bd -literal -offset indent
-struct lwres_context {
-	unsigned int	timeout;	/* time to wait for reply */
-	lwres_uint32_t	serial;		/* serial number state */
-	/*
-	 * For network I/O.
-	 */
-	int		sock;		/* socket to send on */
-	/*
-	 * Function pointers for allocating memory.
-	 */
-	lwres_malloc_t	malloc;
-	lwres_free_t	free;
-	void		*arg;
-	/*
-	 * resolv.conf-like data
-	 */
-	lwres_conf_t	confdata;
-};
-
-typedef struct lwres_context lwres_context_t;
-.Ed
 .Sh DESCRIPTION
 .Fn lwres_context_create
-is used to create a
+creates a
 .Dv lwres_context_t
-structure for use in lightweight resolver operations and associate
-general purpose memory allocation functions with that structure.
-.Fa *contextp
-is a pointer to a
-.Dv "struct lwres_context" .
-It must be non-NULL, which in turn implies that
-.Fa **contextp
-is also non-NULL.
+structure for use in lightweight resolver operations.
+It holds a socket and other data needed for communicating
+with a resolver daemon.
+The new
+.Dv lwres_context_t
+is returned throught
+.Fa contextp ,
+a pointer to a
+.Dv "lwres_context_t"
+pointer.  This 
+.Dv "lwres_context_t"
+pointer must initially be NULL, and is modified 
+to point to the newly created
+.Dv "lwres_context_t" .
+.Pp
+When the lightweight resolver needs to perform dynamic memory
+allocation, it will call
+.Fa malloc_function
+to allocate memory and
+.Fa free_function 
+to free it.  If 
 .Fa malloc_function
 and
-.Fa free_function
-are pointers to the functions the context should use for allocating
-and freeing memory respectively.
-Both function pointers must either be non-NULL or NULL.
-It is not permitted to use a custom allocator - i.e
-.Fa malloc_function
-is non-NULL -
-with a NULL
-.Fa free_function
-or vice versa.
-If both function pointers are NULL, the lightweight resolver's
-internal allocation routines which call
+.Fa free_function 
+are NULL, memory is allocated using
 .Xr malloc 3
 and
-.Xr free 3
-are used.
+.Xr free 3 .
+It is not permitted to have a NULL
+.Fa malloc_function
+and a non-NULL
+.Fa free_function
+or vice versa.
 .Fa arg
-is passed as the initial parameter to the memory
-allocation functions.
-The argument is passed but not used in the internal allocation
-and deallocation routines.
+is passed as the first parameter to the memory
+allocation functions.  
+If
+.Fa malloc_function
+and
+.Fa free_function
+are NULL,
+.Fa arg 
+is unused and should be passed as NULL.
+.P
 Once memory for the structure has been allocated,
-.Xr lwres_conf_init 3
-is called to initialise it.
-The structure is then returned via
+it is initialized using
+.Xr lwres_conf_init 3 
+and returned via
 .Fa *contextp .
 .Pp
-A
-.Dv "struct lwres_context"
-is destroyed by
-.Fn lwres_context_destroy.
-.Fa **contextp
+.Fn lwres_context_destroy
+destroys a 
+.Dv "lwres_context_t" ,
+closing its socket.
+.Fa contextp
 is a pointer to a pointer to the context that is to be destroyed.
-It must be non-NULL, as should
-.Fa *contextp .
-If the context has an open socket, it is closed before the structure
-is discarded.
+The pointer will be set to NULL when the context has been destroyed.
 .Pp
-The context's serial number is controlled with
+The context holds a serial number that is used to identify resolver
+request packets and associate responses with the corresponding requests.
+This serial number is controlled using
 .Fn lwres_context_initserial
 and
 .Fn lwres_context_nextserial .
-Both require that
-.Fa ctx
-is not NULL.
 .Fn lwres_context_initserial
 sets the serial number for context
 .Fa *ctx
 to
 .Fa serial .
 .Fn lwres_context_nextserial
-returns the current serial number for the context and increments
-.Dv  ctx->serial .
+increments the serial number and returns the previous value.
 .Pp
 Memory for a lightweight resolver context is allocated and freed using
 .Fn lwres_context_allocmem
@@ -182,38 +168,16 @@ frees
 .Fa len
 bytes of space starting at location
 .Fa mem .
-It has assertion checks to ensure that
-.Fa mem
-is not null and
-.Fa len
-is not zero.
-.Pp
-If the lightweight resolver's memory allocation functions are used,
-.Fa len
-bytes in the allocated buffer will be set to '0xe5' on allocation
-or '0xa9' when they are freed.
 .Pp
 .Fn lwres_context_sendrecv
 performs I/O for the context
 .Fa ctx .
-Data are read and written from the context's socket
-.Dv ctx->sock .
+Data are read and written from the context's socket.
 It writes data from
 .Fa sendbase
-- typically a DNS query -
+- typically a lightweight resolver query packet -
 and waits for a reply which is copied to the receive buffer at
 .Fa recvbase .
-.Fa sendbase
-is a pointer to the
-.Fa sendlen
-bytes of data that are to be sent using
-.Xr sendto 2.
-Up to
-.Fn recvlen
-bytes of data that are returned by a call to
-.Xr recvfrom 2
-on the socket are copied to
-.Fa recvbase .
 The number of bytes that were written to this receive buffer is
 returned in
 .Fa *recvd_len .
@@ -223,9 +187,9 @@ returns
 .Er LWRES_R_NOMEMORY
 if memory for the
 .Dv "struct lwres_context"
-could not be allocated, otherwise
+could not be allocated, 
 .Er LWRES_R_SUCCESS
-is returned.
+otherwise.
 .Pp
 Successful calls to the memory allocator
 .Fn lwres_context_allocmem
@@ -239,18 +203,10 @@ completes successfully.
 .Er LWRES_R_IOERROR
 is returned if an I/O error occurs and
 .Er LWRES_R_TIMEOUT
-is returned if the
-.Xr recvfrom 2
-call times out.
+is returned if
+.Fn lwres_context_sendrecv
+times out waiting for a response.
 .Sh SEE ALSO
 .Xr lwres_conf_init 3 ,
 .Xr malloc 3 ,
-.Xr free 3 ,
-.Xr close 2 ,
-.Xr memset 3 ,
-.Xr sendto 2 ,
-.Xr recvfrom 2 .
-.Sh BUGS
-The
-.Dv lwres_context_t
-structures and the functions which operate on them are not thread-safe.
+.Xr free 3
diff --git a/doc/man/lwres/lwres_gabn.3 b/doc/man/lwres/lwres_gabn.3
index 4e0b353854..b5d6fc038e 100644
--- a/doc/man/lwres/lwres_gabn.3
+++ b/doc/man/lwres/lwres_gabn.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_gabn.3,v 1.3 2000/08/01 01:21:05 tale Exp $
+.\" $Id: lwres_gabn.3,v 1.4 2000/09/28 22:36:25 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GABN 3
@@ -26,7 +26,7 @@
 .Nm lwres_gabnresponse_parse ,
 .Nm lwres_gabnresponse_free ,
 .Nm lwres_gabnrequest_free
-.Nd lightweight resolver getaddrbyname functions
+.Nd lightweight resolver getaddrbyname message handling
 .Sh SYNOPSIS
 .Fd #include <lwres/lwres.h>
 .Fd
@@ -69,11 +69,10 @@
 .Fa "lwres_gabnrequest_t **structp"
 .Fc
 .Sh DESCRIPTION
-These functions implement the lightweight resolver's getaddrbyname opcode
-.Dv LWRES_OPCODE_GETADDRSBYNAME .
-They provide a forward lookup mechanism, mapping a hostname to its
-address or addresses.
-.Pp
+These are low-level routines for creating and parsing
+lightweight resolver name-to-address lookup request and 
+response messages.
+.P
 There are four main functions for the getaddrbyname opcode.
 One render function converts a getaddrbyname request structure -
 .Dv lwres_gabnrequest_t -
@@ -87,7 +86,7 @@ This is complemented by a parse function which converts a packet in
 canonical format to a getaddrbyname response structure.
 .Pp
 These structures are defined in
-.Pa lwres/lwres.h .
+.Pa <lwres/lwres.h> .
 They are shown below.
 .Bd -literal -offset indent
 #define LWRES_OPCODE_GETADDRSBYNAME	0x00010001U
diff --git a/doc/man/lwres/lwres_gai_strerror.3 b/doc/man/lwres/lwres_gai_strerror.3
index d36140f3c0..4d554eebbd 100644
--- a/doc/man/lwres/lwres_gai_strerror.3
+++ b/doc/man/lwres/lwres_gai_strerror.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_gai_strerror.3,v 1.3 2000/08/01 01:21:12 tale Exp $
+.\" $Id: lwres_gai_strerror.3,v 1.4 2000/09/28 22:36:26 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GAI_STRERROR 3
@@ -30,16 +30,11 @@
 .Fa "int ecode"
 .Fc
 .Sh DESCRIPTION
-.Fn gai_strerror
-returns a suitable error message for the error code
-.Fa ecode .
-The message \*qinvalid error code\*q is returned if
-.Fa ecode
-is out of range.
+.Fn lwres_gai_strerror
+returns an error message corresponding to an error code returned by
+.Fn getaddrinfo .
 The following error codes and their meaning are defined in
 .Aq Pa include/lwres/netdb.h .
-They can be returned by
-.Fn getaddrinfo .
 .Bl -tag -width EAI_ADDRFAMILY -offset indent -compact
 .It Dv EAI_ADDRFAMILY
 address family for hostname not supported
@@ -68,17 +63,20 @@ not supported
 .It Dv EAI_SYSTEM
 system error returned in errno
 .El
+The message \*qinvalid error code\*q is returned if
+.Fa ecode
+is out of range.
 .Pp
 .Li ai_flags ,
 .Li ai_family
 and
 .Li ai_socktype
 are elements of the
-.Dv "struct  addrinfo" used by
+.Dv "struct  addrinfo"
+used by
 .Fn lwres_getaddrinfo .
 .Sh SEE ALSO
-.Xr errno 2 ,
-.Xr perror 3 ,
+.Xr strerror 3 ,
 .Xr lwres_getaddrinfo 3 ,
 .Xr getaddrinfo 3 ,
 .Xr RFC2133 .
diff --git a/doc/man/lwres/lwres_getaddrinfo.3 b/doc/man/lwres/lwres_getaddrinfo.3
index 6039a1ff07..a0fc8c3946 100644
--- a/doc/man/lwres/lwres_getaddrinfo.3
+++ b/doc/man/lwres/lwres_getaddrinfo.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_getaddrinfo.3,v 1.3 2000/08/01 01:21:13 tale Exp $
+.\" $Id: lwres_getaddrinfo.3,v 1.4 2000/09/28 22:36:27 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GETADDRINFO 3
@@ -40,7 +40,8 @@
 .Pp
 If the operating system does not provide a
 .Dv "struct addrinfo" ,
-the following structure is used
+the following structure is used:
+.Pp
 .Bd -literal -offset indent
 struct	addrinfo {
 	int		ai_flags;	/* AI_PASSIVE, AI_CANONNAME */
@@ -58,7 +59,7 @@ struct	addrinfo {
 .Fn lwres_getaddrinfo
 is used to get a list of IP addresses and port numbers for host
 .Fa hostname
-and
+and service
 .Fa servname .
 The function is the lightweight resolver's implementation of
 .Fn getaddrinfo
@@ -66,12 +67,12 @@ as defined in RFC2133.
 .Fa hostname
 and
 .Fa servname
-arguments are pointers to null-terminated
+are pointers to null-terminated
 strings or
 .Dv NULL .
 .Fa hostname
-either a host name or a numeric host address string: a dotted decimal
-IPv4 address or an IPv6 hex address.
+is either a host name or a numeric host address string: a dotted decimal
+IPv4 address or an IPv6 address.
 .Fa servname
 is either a decimal port number or a service name as listed in
 .Pa /etc/services .
@@ -103,12 +104,13 @@ When
 .Li ai_socktype
 is zero the caller will accept any socket type.
 .It Li ai_protocol
-indicates which transport protocol is wanted: UDP or TCP.
+indicates which transport protocol is wanted: IPPROTO_UDP or 
+IPPROTO_TCP.
 If
 .Li ai_protocol
 is zero the caller will accept any protocol.
 .It Li ai_flags
-sets some flag bits.
+Flag bits.
 If the
 .Dv AI_CANONNAME
 bit is set, a successful call to
@@ -161,14 +163,9 @@ If
 is set to
 .Dv AI_NUMERICHOST
 it indicates that
-the
-.Dv non-NuLL
 .Fa hostname
-should be treated as a numeric string defining an IPv4 or IPv6 address.
-This will prevent a numeric IPv4 address from being considered as a domain
-name when
-.Fn lwres_getaddrinfo
-is looking for IPv6 addresses or vice versa.
+should be treated as a numeric string defining an IPv4 or IPv6 address
+and no name resolution should be attempted.
 .El
 .Pp
 All other elements of the
@@ -177,14 +174,13 @@ passed via
 .Fa arg
 must be zero.
 .Pp
-If
+An
 .Fa arg
-is not supplied, a
+of
 .Dv NULL
-pointer should be given for this argument.
-It will be treated as if the caller provided an
+is treated as if the caller provided a
 .Dv "struct addrinfo"
-structure initialized to zero with
+initialized to zero with
 .Li ai_family set to
 .Li PF_UNSPEC .
 .Pp
@@ -195,7 +191,8 @@ is a pointer to a linked list of one or more
 .Dv addrinfo
 structures.
 Each
-.Dv "struct addrinfo" in this list cn be processed by following
+.Dv "struct addrinfo" 
+in this list cn be processed by following
 the
 .Li ai_next
 pointer, until a
@@ -203,7 +200,7 @@ pointer, until a
 pointer is encountered.
 The three members
 .Li ai_family ,
-ai_socktype,
+.Li ai_socktype ,
 and
 .Li ai_protocol
 in each
@@ -230,7 +227,8 @@ is released by
 .Fn lwres_freeaddrinfo .
 .Fa ai
 is a pointer to a
-.Dv "struct addrinfo" created by a call to
+.Dv "struct addrinfo" 
+created by a call to
 .Fn lwres_getaddrinfo .
 .Sh RETURN VALUES
 .Fn lwres_getaddrinfo
@@ -247,13 +245,13 @@ are
 returns
 .Er EAI_NONAME .
 .Sh SEE ALSO
+.Xr lwres 3 ,
 .Xr lwres_getaddrinfo 3 ,
 .Xr lwres_freeaddrinfo 3 ,
 .Xr lwres_gai_strerror 3 ,
 .Xr RFC2133 ,
 .Xr getservbyname 3 ,
-.Xr bind 2
-.Xr connect 2
+.Xr bind 2 ,
 .Xr connect 2 ,
 .Xr sendto 2 ,
 .Xr sendmsg 2 ,
diff --git a/doc/man/lwres/lwres_gethostent.3 b/doc/man/lwres/lwres_gethostent.3
index c997d6f2e6..bca29524cf 100644
--- a/doc/man/lwres/lwres_gethostent.3
+++ b/doc/man/lwres/lwres_gethostent.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_gethostent.3,v 1.3 2000/08/01 01:21:21 tale Exp $
+.\" $Id: lwres_gethostent.3,v 1.4 2000/09/28 22:36:28 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GETHOSTENT 3
@@ -96,16 +96,15 @@
 .Fa "void"
 .Fc
 .Sh DESCRIPTION
-These functions define the interface to the lightweight resolver
-daemon \fPNOT IF IT IS GOING AWAY\fP
-for looking up hostnames and addresses. They are similar to the
-standard
+These functions provide hostname-to-address and
+address-to-hostname lookups by means of the lightweight resolver.
+They are similar to the standard
 .Xr gethostent 3
-functions provided by as part of the standard system software.
+functions provided by most operating systems.
 They use a
 .Dv "struct hostent"
 which is usually defined in
-.Pa namedb.h .
+.Pa <namedb.h> .
 .Bd -literal
 struct	hostent {
 	char	*h_name;	/* official name of host */
@@ -149,19 +148,17 @@ is the first address in
 .Fn lwres_sethostent_r
 and
 .Fn lwres_endhostent_r
-are empty stub functions which do nothing.
-They are provided as placeholders so that calls to the system's
-.Xr gethostent 3
-functions can simply be #defined to their
-.Xr lwres_res_gethost
-equivalents.
-See
-.Pa lwres/netdb.h .
+provide iteration over the known host entries on systems that
+provide such functionality through facilities like
+.Pa /etc/hosts
+or NIS.  The lightweight resolver does not currently implement
+these functions; it only provides them as stub functions that always
+return failure.
 .Pp
 .Fn lwres_gethostbyname
 and
 .Fn lwres_gethostbyname2
-lookup the hostname
+look up the hostname
 .Fa name .
 .Fn lwres_gethostbyname
 always looks for an IPv4 address while
@@ -173,9 +170,6 @@ either
 or
 .Dv PF_INET6
 - IPv4 or IPV6 addresses respectively.
-Both functions call
-.Fn lwres_getipnodebyname
-to look up the hostname.
 Successful calls of the functions return a
 .Dv "struct hostent" for
 the name that was looked up.
@@ -196,19 +190,9 @@ bytes and protocol family
 .Dv PF_INET
 or
 .Dv PF_INET6 .
-It calls
-.Fn lwres_getipnodebyaddr
-to do the reverse lookup.
-.Pp
 .Fn lwres_gethostbyname_r
 is a thread-safe function for forward lookups.
-It also calls
-.Fn lwres_getipnodebyname
-to lookup the hostname
-.Fa name .
-If
-.Fn lwres_getipnodebyname
-encounters an error, the error code is returned in
+If an error occurs, an error code is returned in
 .Fa *error .
 .Fa resbuf
 is a pointer to a
@@ -232,7 +216,7 @@ Successful calls to
 return
 .Fa resbuf ,
 which is a pointer to the
-.Fn "struct hostent"
+.Dv "struct hostent"
 it created.
 .Pp
 .Fn lwres_gethostbyaddr_r
@@ -246,13 +230,8 @@ and is of protocol family
 .Dv PF_INET
 or
 .Dv PF_INET6 .
-.Fn lwres_gethostbyaddr_r
-calls
-.Fn lwres_getipnodebyaddr
-to do the work.
-If this function encounters an error, the error code is returned in
+If an error occurs, the error code is returned in
 .Fa *error .
-Like
 The other function parameters are identical to those in
 .Fn lwres_gethostbyname_r .
 .Fa resbuf
@@ -287,36 +266,26 @@ The functions
 .Fn lwres_gethostbyaddr ,
 and
 .Fn lwres_gethostent
-are not thread-safe because they free any memory that had been allocated
-in a previous call to those functions before they perform a lookup.
-They also set the global variable
+return NULL to indicate an error.  In this case the global variable
 .Dv lwres_h_errno
-when they return.
-The values of this variable are defined in
-.Pa lwres/netdb.h .
-The values and their meaning are defined as follows:
+will contain one of the following error codes defined in
+.Pa <lwres/netdb.h> :
 .Bl -tag -width HOST_NOT_FOUND
-.It Li NETDB_INTERNAL
-Internal Error - see
-.Li errno
-.It Li NETDB_SUCCESS
-no problem
 .It Li HOST_NOT_FOUND
-Authoritative Answer Host not found
+The host or address was not found.
 .It Li TRY_AGAIN
-Non-Authoritive Answer Host not found, or
-.Dv SERVERFAIL
+A recoverable error occurred, e.g., a timeout.
+Retrying the lookup may succeed.
 .It Li NO_RECOVERY
-Non recoverable errors,
-.Dv FORMERR ,
-.Dv REFUSED ,
-or
-.Dv NOTIMP
+A non-recoverable error occurred.
 .It Li NO_DATA
-Valid name, but no data record of requested type
-.It Li NO_ADDRESS
-no address, so look for MX record
+The name exists, but has no address information
+associated with it (or vice versa in the case
+of a reverse lookup).  The code NO_ADDRESS
+is accepted as a synonym for NO_DATA for backwards
+compatibility.
 .El
+.Pp
 .Xr lwres_hstrerror 3
 translates these error codes to suitable error messages.
 .Pp
@@ -355,7 +324,7 @@ was too small, both
 and
 .Fn lwres_gethostbyaddr_r
 set the global variable
-.DV errno
+.Dv errno
 to
 .Er ERANGE .
 .Sh SEE ALSO
@@ -363,26 +332,13 @@ to
 .Xr lwres_getipnode 3 ,
 .Xr lwres_hstrerror 3
 .Sh BUGS
-Although
 .Fn lwres_gethostbyname ,
 .Fn lwres_gethostbyname2 ,
 .Fn lwres_gethostbyaddr
 and
 .Fn lwres_endhostent
-call thread-safe functions to perform lookups, these 3 functions
-are not thread-safe because they set the global variable
-.Dv lwres_h_errno
-which could
-overwritten if two or more threads called these functions
-simultaneously.
-They also release any memory that had been allocated in a previous call
-to these functions.
-This emulates the semantics of their equivalent functions in the
-system's
-.Xr gethostent 3
-functions which use a static buffer that gets overwritten in subsequent
-calls to those routines.
-.Pp
+are not thread safe; they return pointers to static data and 
+provide error codes through a global variable.
 Thread-safe versions for name and address lookup are provided by
 .Fn lwres_gethostbyname_r ,
 and
diff --git a/doc/man/lwres/lwres_getipnode.3 b/doc/man/lwres/lwres_getipnode.3
index ff4b80c902..73f2b3537b 100644
--- a/doc/man/lwres/lwres_getipnode.3
+++ b/doc/man/lwres/lwres_getipnode.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_getipnode.3,v 1.3 2000/08/01 01:21:24 tale Exp $
+.\" $Id: lwres_getipnode.3,v 1.4 2000/09/28 22:36:29 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GETIPNODE 3
@@ -23,9 +23,9 @@
 .Nm lwres_getipnodebyname ,
 .Nm lwres_getipnodebyaddr ,
 .Nm lwres_freehostent
-.Nd lookup functions for the lightweight resolver
+.Nd lightweight resolver nodename / address translation API
 .Sh SYNOPSIS
-.Fd #include <lwres/lwres.h>
+.Fd #include <lwres/netdb.h>
 .Fd
 .Ft struct hostent *
 .Fo lwres_getipnodebyname
@@ -46,10 +46,14 @@
 .Fa "struct hostent *he"
 .Fc
 .Sh DESCRIPTION
-These functions use a
+These functions perform thread safe, protocol independent
+nodename-to-address and address-to-nodename 
+translation as defined in RFC2553.
+.Pp
+They use a
 .Dv "struct hostent"
-which is usually defined in
-.Pa namedb.h .
+which is defined in
+.Pa namedb.h :
 .Bd -literal
 struct	hostent {
 	char	*h_name;	/* official name of host */
@@ -68,7 +72,7 @@ The official (canonical) name of the host.
 .It Li h_aliases
 A NULL-terminated array of alternate names (nicknames) for the host.
 .It Li h_addrtype
-The type of address being returned -
+The type of address being returned - usually
 .Dv PF_INET
 or
 .Dv PF_INET6 .
@@ -81,92 +85,53 @@ terminated array of network addresses for the host.
 Host addresses are returned in network byte order.
 .El
 .Pp
-For backward compatibility with very old software,
-.Li h_addr
-is the first address in
-.Li h_addr_list.
-.Pp
 .Fn lwres_getipnodebyname
-looks up the hostname
-.Fa name
-of protocol family
-.Fa af .
+looks up addresses of protocol family
+.Fa af 
+for the hostname
+.Fa name .
 The
 .Fa flags
-parameter sets bits that indicate how IPv6 and IPv4 addresses
-should presented.
-The value of those flags are:
+parameter contains ORed flag bits to 
+specify the types of addresses that are searched
+for, and the types of addresses that are returned. 
+The flag bits are:
 .Bl -tag -width AI_ADDRCONFIG
 .It Li AI_V4MAPPED
-return an IPv4 address mapped to an IPv6 address
+This is used with an
+.Fa af
+of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
+IPv6 addresses.
 .It Li AI_ALL
-return all possible addresses
+This is used with an
+.Fa af
+of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
+If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
+IPv6 addresses.
 .It Li AI_ADDRCONFIG
-only return an IPv6 or IPv4 address if here is an active network
-interface of that type.
+Only return an IPv6 or IPv4 address if here is an active network
+interface of that type.  This is not currently implemented
+in the BIND 9 lightweight resolver, and the flag is ignored.
 .It Li AI_DEFAULT
-this default sets the
+This default sets the
 .Li AI_V4MAPPED
 and
 .Li AI_ADDRCONFIG
 flag bits.
 .El
 .Pp
-The value of
-.Dv AF_INET6
-is sometimes added to
-.Fa flags .
-When
-.Fa flags
-is set to
-.Li "AI_V4MAPPED + AF_INET6"
-.Fn lwres_getipnodebyname
-will look for an IPv6 address and if this is not found it will look
-for an IPv4 address and map it to an IPv6 address.
-When
-.Fa flags
-is
-.Li "AI_ALL + AI_V4MAPPED + AF_INET6" ,
-.Fn lwres_getipnodebyname
-returns mapped IPv4 addresses and IPv6 addresses.
-.Fn lwres_getipnodebyname
-calls
-.Fn lwres_context_create
-to create a resolver context for the lookup and
-then calls
-.Fn lwres_getaddrsbyname
-to lookup the name using that resolver context.
-.Pp
 .Fn lwres_getipnodebyaddr
-performs a thread-safe reverse lookup
+performs a reverse lookup
 of address
 .Fa src
 which is
 .Fa len
 bytes long.
 .Fa af
-denotes the protocol family:
+denotes the protocol family, typically
 .Dv PF_INET
 or
 .Dv PF_INET6 .
-.Fn lwres_getipnodebyaddr
-also sets up a resolver context by calling
-.Fn lwres_context_create.
-It then calls
-.Fn lwres_getnamebyaddr
-to make the query.
-.Pp
-Both
-.Fn lwres_getipnodebyname
-and
-.Fn lwres_getipnodebyaddr
-will free any memory that was allocated during intermediate stages of the
-lookup by calling
-.Fn lwres_gnbaresponse_free .
-Both functions call
-.Fn lwres_getipnodebyaddr
-immediately before they return so that the created resolver context
-gets discarded.
 .Pp
 .Fn lwres_freehostent
 releases all the memory associated with
@@ -193,37 +158,29 @@ to an approriate error code and the function returns a
 .Dv NULL
 pointer.
 The error codes and their meanings are defined in
-.Pa lwres/netdb.h .
+.Pa <lwres/netdb.h> :
 .Bl -tag -width HOST_NOT_FOUND
-.It Li NETDB_INTERNAL
-Internal Error - see
-.Li errno
-.It Li NETDB_SUCCESS
-no problem
 .It Li HOST_NOT_FOUND
-Authoritative Answer Host not found
-.It Li TRY_AGAIN
-Non-Authoritive Answer Host not found, or
-.Dv SERVERFAIL
-.It Li NO_RECOVERY
-Non recoverable errors,
-.Dv FORMERR ,
-.Dv REFUSED ,
-or
-.Dv NOTIMP
-.It Li NO_DATA
-Valid name, but no data record of requested type
+No such host is known.
 .It Li NO_ADDRESS
-no address, so look for MX record
+The server recognised the request and the name but no address is
+available.  Another type of request to the name server for the
+domain might return an answer.
+.It Li TRY_AGAIN
+A temporary and possibly transient error occurred, such as a
+failure of a server to respond.  The request may succeed if
+retried.
+.It Li NO_RECOVERY
+An unexpected failure occurred, and retrying the request
+is pointless.
 .El
 .Pp
 .Xr lwres_hstrerror 3
 translates these error codes to suitable error messages.
 .Sh SEE ALSO
-.Xr lwres_res_getaddrsbyname 3 ,
-.Xr lwres_res_context_create 3 ,
-.Xr lwres_res_context_destroy 3 ,
-.Xr lwres_res_gnbaresponse_free 3 ,
-.Xr lwres_res_getaddrsbyaddr 3 ,
-.Xr free 3 ,
+.Xr RFC2553 ,
+.Xr lwres 3 ,
+.Xr lwres_gethostent 3 ,
+.Xr lwres_getaddrinfo 3 ,
+.Xr lwres_getnameinfo 3 ,
 .Xr lwres_hstrerror 3 .
diff --git a/doc/man/lwres/lwres_getnameinfo.3 b/doc/man/lwres/lwres_getnameinfo.3
index c7e8986735..0c4c498baf 100644
--- a/doc/man/lwres/lwres_getnameinfo.3
+++ b/doc/man/lwres/lwres_getnameinfo.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_getnameinfo.3,v 1.4 2000/08/01 01:21:28 tale Exp $
+.\" $Id: lwres_getnameinfo.3,v 1.5 2000/09/28 22:36:30 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GETNAMEINFO 3
@@ -23,7 +23,7 @@
 .Nm lwres_getnameinfo
 .Nd lightweight resolver socket address structure to hostname and service name
 .Sh SYNOPSIS
-.Fd #include <lwres/lwres.h>
+.Fd #include <lwres/netdb.h>
 .Fd
 .Ft int
 .Fo lwres_getnameinfo
@@ -64,50 +64,33 @@ It is
 bytes long.
 The maximum length of the service name is
 .Li NI_MAXSERV
-- 32 - bytes.
+- 32 bytes.
 .Pp
 The
 .Fa flags
 argument sets the following bits:
 .Bl -tag -width NI_NUMERICSERV
 .It Li NI_NOFQDN
-a fully qualified domain name is not required for local hosts.
+A fully qualified domain name is not required for local hosts.
 The local part of the fully qualified domain name is returned instead.
 .It Li NI_NUMERICHOST
-the address in the
-.Dv sockaddr
-structure is presented as a dotted-decimal string for an IPv4
-address or an IPv6 hex address if the hostname is not found in the
-DNS.
+Return the address in numeric form, as if calling inet_ntop(),
+instead of a host name.
 .It Li NI_NAMEREQD
-a name is required. If the hostname cannot be found in the DNS and
-this flag is set, a non-zero error code
-is returned.
+A name is required. If the hostname cannot be found in the DNS and
+this flag is set, a non-zero error code is returned.
+If the hostname is not found and the flag is not set, the 
+address is returned in numeric form.
 .It Li NI_NUMERICSERV
-service name is returned as a digit string representing the port number.
+The service name is returned as a digit string representing the port number.
 .It Li NI_DGRAM
-the service uses a datagram transport protocol
+Specifies that the service being looked up is a datagram
+service,  and causes getservbyport() to be called with a second
+argument of "udp" instead of its default of "tcp".  This is required
+for the few ports (512-514) that have different services for UDP and
+TCP.
 .El
 .Pp
-When a numeric host address string is needed,
-.Fn lwres_getnameinfo
-calls
-.Fn lwres_net_ntop
-to generate an IPv6 hex address or a dotted decimal IPv4 address.
-If required,
-.Fn lwres_getnameinfo
-will create a resolver context by calling
-.Fn lwres_context_create
-and then using
-.Fn lwres_getnamebyaddr
-to perform the reverse lookup.
-Any memory allocated during that reverse lookup will be
-freed by calling
-.Fn lwres_gnbaresponse_free .
-.Fn lwres_context_destroy
-is called immediately before
-.Fn lwres_getnameinfo
-returns so that the created resolver context gets discarded.
 .Sh RETURN VALUES
 .Fn lwres_getnameinfo
 returns 0 on success or a non-zero error code if an error occurs.
@@ -135,12 +118,13 @@ returns 0 on success or a non-zero error code if an error occurs.
 .\" is the wrong number of bytes for the address in
 .\" Fa sa .
 .Sh SEE ALSO
-.Xr getnameinfo 3 ,
 .Xr RFC2133 ,
 .Xr getservbyport 3 ,
-.Xr lwres_res_net_ntop 3 ,
-.Xr lwres_res_context_create 3,
-.Xr lwres_res_getnamebyaddr 3,
-.Xr lwres_res_gnbaresponse_free 3 ,
-.Xr lwres_res_context_destroy 3 ,
-.Xr lwres_res_net_ntop 3 .
+.Xr lwres 3 ,
+.Xr lwres_getnameinfo 3 ,
+.Xr lwres_getnamebyaddr 3,
+.Xr lwres_net_ntop 3 .
+.Sh BUGS
+RFC2133 fails to define what the nonzero return values of
+.Xr getnameinfo 3 
+are.
diff --git a/doc/man/lwres/lwres_gnba.3 b/doc/man/lwres/lwres_gnba.3
index d25661261b..d08213b6ef 100644
--- a/doc/man/lwres/lwres_gnba.3
+++ b/doc/man/lwres/lwres_gnba.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_gnba.3,v 1.3 2000/08/01 01:21:29 tale Exp $
+.\" $Id: lwres_gnba.3,v 1.4 2000/09/28 22:36:31 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GNBA 3
@@ -26,7 +26,7 @@
 .Nm lwres_gnbaresponse_parse ,
 .Nm lwres_gnbaresponse_free ,
 .Nm lwres_gnbarequest_free
-.Nd lightweight resolver getnamebyaddress functions
+.Nd lightweight resolver getnamebyaddress message handling
 .Sh SYNOPSIS
 .Fd #include <lwres/lwres.h>
 .Fd
@@ -69,10 +69,9 @@
 .Fa "lwres_gnbarequest_t **structp"
 .Fc
 .Sh DESCRIPTION
-These functions implement the lightweight resolver's getnamebyaddr opcode
-.Dv LWRES_OPCODE_GETNAMEBYADDR .
-They provide a reverse lookup mechanism, mapping an address to its
-hostname.
+These are low-level routines for creating and parsing
+lightweight resolver address-to-name lookup request and 
+response messages.
 .Pp
 There are four main functions for the getnamebyaddr opcode.
 One render function converts a getnamebyaddr request structure -
diff --git a/doc/man/lwres/lwres_noop.3 b/doc/man/lwres/lwres_noop.3
index 3846f41bd1..5d779818dc 100644
--- a/doc/man/lwres/lwres_noop.3
+++ b/doc/man/lwres/lwres_noop.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_noop.3,v 1.3 2000/08/01 01:21:48 tale Exp $
+.\" $Id: lwres_noop.3,v 1.4 2000/09/28 22:36:33 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_NOOP 3
@@ -26,7 +26,7 @@
 .Nm lwres_noopresponse_parse ,
 .Nm lwres_noopresponse_free ,
 .Nm lwres_nooprequest_free
-.Nd lightweight resolver no-op functions
+.Nd lightweight resolver no-op message handling
 .Sh SYNOPSIS
 .Fd #include <lwres/lwres.h>
 .Fd
@@ -69,10 +69,11 @@
 .Fa "lwres_nooprequest_t **structp"
 .Fc
 .Sh DESCRIPTION
-These functions implement the lightweight resolver's no-op opcode
-.Dv LWRES_OPCODE_NOOP .
-This is analogous to a \*qping\*q test: a packet is sent to the
-lightweight resolver daemon and is simply echoed back.
+These are low-level routines for creating and parsing
+lightweight resolver no-op request and response messages.
+.P
+The no-op message is analogous to a \*qping\*q packet: 
+a packet is sent to the resolver daemon and is simply echoed back.
 The opcode is intended to allow a client to determine if the server is
 operational or not.
 .Pp
diff --git a/lib/lwres/man/lwres_buffer.3 b/lib/lwres/man/lwres_buffer.3
index ec69ae6c87..172d0ba10e 100644
--- a/lib/lwres/man/lwres_buffer.3
+++ b/lib/lwres/man/lwres_buffer.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_buffer.3,v 1.3 2000/08/01 01:20:26 tale Exp $
+.\" $Id: lwres_buffer.3,v 1.4 2000/09/28 22:36:23 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_BUFFER 3
@@ -118,24 +118,13 @@
 .Fa "unsigned int length"
 .Fc
 .Sh DESCRIPTION
-These functions use the following structure as a buffer descriptor to
-manage the actual storage:
-.Bd -literal -offset indent
-typedef struct lwres_buffer lwres_buffer_t;
-struct lwres_buffer {
-	unsigned int		magic;
-	unsigned char 	       *base;
-	/* The following integers are byte offsets from 'base'. */
-	unsigned int		length;
-	unsigned int		used;
-	unsigned int 		current;
-	unsigned int 		active;
-};
-.Ed
-The main reason for making the buffer structure public is so that
-buffer operations can be implemented using macros.
-Applications should not manipulate this structure directly.
-They should use the functions listed below.
+
+
+These functions provide bounds checked access to a region of memory
+where data is being read or written.
+They are based on, and similar to, the
+.Va isc_buffer_
+functions in the ISC library.
 .Pp
 A buffer is a region of memory, together with a set of related
 subregions.
@@ -168,33 +157,42 @@ Initially, the active region is empty.
 If the current offset advances beyond the chosen offset,
 the active region will also be empty.
 .Pp
-Except for
-.Fn lwres_buffer_init ,
-all of the buffer managements functions contain an assertion check
-that
-.Fa b
-is a pointer to a valid lightweight resolver buffer.
+.Bd -literal -offset indent
+ 
+   /------------entire length---------------\\
+   /----- used region -----\\/-- available --\\
+   +----------------------------------------+
+   | consumed  | remaining |                |
+   +----------------------------------------+
+   a           b     c     d                e
+ 
+  a == base of buffer.
+  b == current pointer.  Can be anywhere between a and d.
+  c == active pointer.  Meaningful between b and d.
+  d == used pointer.
+  e == length of buffer.
+ 
+  a-e == entire length of buffer.
+  a-d == used region.
+  a-b == consumed region.
+  b-d == remaining region.
+  b-c == optional active region.
+.Ed
 .Pp
 .Fn lwres_buffer_init
-makes the
-.Dv "struct lwres_buffer"
-referenced by
+initializes the
+.Dv lwres_buffer_t
 .Fa *b
-to be associated with a memory region of size
+and assocates it with the memory region of size
 .Fa length
 bytes starting at location
 .Fa base.
-The function checks that
-.Fa *b is not
-.Dv NULL .
 .Pp
-The
-.Dv lwres_buffer_t
-.Fa *b
-is invalidated by
-.Fn lwres_buffer_invalidate .
-.Fa *b
-must be a valid lightweight resolver buffer.
+.Fn lwres_buffer_invalidate
+marks the buffer
+.Fa *b 
+as invalid.  Invalidating a buffer after use is not required,
+but makes it possible to catch its possible accidental use.
 .Pp
 The functions
 .Fn lwres_buffer_add
@@ -206,70 +204,62 @@ buffer
 by
 .Fa n
 bytes.
-.Fa *b
 .Fn lwres_buffer_add
 checks for buffer overflow and
 .Fn lwres_buffer_subtract
 checks for underflow.
 These functions do not allocate or deallocate memory.
 They just change the value of
-.Li b->used .
+.Li used .
 .Pp
-A lightweight resolver buffer is re-initialised by
+A buffer is re-initialised by
 .Fn lwres_buffer_clear .
 The function sets
-.Li b->used ,
-.Li b->current
+.Li used ,
+.Li current
 and
-.Li b->active
+.Li active
 to zero.
 .Pp
 .Fn lwres_buffer_first
 makes the consumed region of buffer
 .Fa *p
 empty by setting
-.Li b->current
-to zero: the start of the buffer.
+.Li current
+to zero (the start of the buffer).
 .Pp
-The consumed region of buffer
+.Fn lwres_buffer_forward 
+increases the consumed region of buffer
 .Fa *b
-is increased by
+by
 .Fa n
-bytes
-using
-.Fn lwres_buffer_forward .
-The function checks for buffer overflow.
+bytes, checking for overflow.
 Similarly,
 .Fn lwres_buffer_back
 decreases buffer
 .Fa b 's
 consumed region by
 .Fa n
-bytes and checks for buffer underflow.
+bytes and checks for underflow.
 .Pp
 .Fn lwres_buffer_getuint8
 reads an unsigned 8-bit integer from
 .Fa *b
 and returns it.
-The function checks that it does not read past the end of the buffer's
-consumed region.
 .Fn lwres_buffer_putuint8
 writes the unsigned 8-bit integer
 .Fa val
 to buffer
 .Fa *b .
-It checks that the buffer has available space for
-.Fa val .
 .Pp
 .Fn lwres_buffer_getuint16
 and
 .Fn lwres_buffer_getuint32
 are identical to
 .Fn lwres_buffer_putuint8
-except that they respectively read an unsigned 16-bit or 32-bit integer from
-.Fa b
-converting it from network byte order to host byte order before
-returning its value.
+except that they respectively read an unsigned 16-bit or 32-bit integer 
+in network byte order from
+.Fa b .
 Similarly,
 .Fn lwres_buffer_putuint16
 and
@@ -278,7 +268,7 @@ writes the unsigned 16-bit or 32-bit integer
 .Fa val
 to buffer
 .Fa b ,
-converting it from host byte order to network byte order.
+in network byte order.
 .Pp
 Arbitrary amounts of data are read or written from a lightweight
 resolver buffer with
@@ -301,23 +291,4 @@ bytes of memory from
 .Fa b
 to
 .Fa base .
-For both functions,
-.Fa base
-should point to at least
-.Fa length
-bytes of valid memory.
-.Fa base
-.Sh RETURN VALUES
-.Fn lwres_buffer_getuint8 ,
-.Fn lwres_buffer_getuint16
-and
-.Fn lwres_buffer_getuint32
-return an 8-, 16- or 32-bit unsigned integer respectively from the
-current offset in buffer
-.Fa b .
-The 16- and 32-bit quantities are presented in host byte order even
-though they are stored in network byte order inside the buffer.
 .Sh SEE ALSO
-.Sh BUGS
-Buffers have no synchronization.
-Clients must ensure exclusive access for thread-safe operations.
diff --git a/lib/lwres/man/lwres_context.3 b/lib/lwres/man/lwres_context.3
index 2ae8205992..5e3019a840 100644
--- a/lib/lwres/man/lwres_context.3
+++ b/lib/lwres/man/lwres_context.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_context.3,v 1.3 2000/08/01 01:20:52 tale Exp $
+.\" $Id: lwres_context.3,v 1.4 2000/09/28 22:36:24 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_CONTEXT 3
@@ -27,7 +27,7 @@
 .Nm lwres_context_freemem ,
 .Nm lwres_context_allocmem ,
 .Nm lwres_context_sendrecv
-.Nd lightweight resolver memory allocation routines
+.Nd lightweight resolver context management
 .Sh SYNOPSIS
 .Fd #include <lwres/lwres.h>
 .Fd
@@ -43,14 +43,14 @@
 .Fa "lwres_context_t **contextp"
 .Fc
 .Ft void
-.Fo lwres_context_nextserial
-.Fa "lwres_context_t *ctx"
-.Fc
-.Ft lwres_uint32_t
 .Fo lwres_context_initserial
 .Fa "lwres_context_t *ctx"
 .Fa "lwres_uint32_t serial"
 .Fc
+.Ft lwres_uint32_t
+.Fo lwres_context_nextserial
+.Fa "lwres_context_t *ctx"
+.Fc
 .Ft void
 .Fo lwres_context_freemem
 .Fa "lwres_context_t *ctx"
@@ -71,95 +71,81 @@
 .Fa "int recvlen"
 .Fa "int *recvd_len"
 .Fc
-.Bd -literal -offset indent
-struct lwres_context {
-	unsigned int	timeout;	/* time to wait for reply */
-	lwres_uint32_t	serial;		/* serial number state */
-	/*
-	 * For network I/O.
-	 */
-	int		sock;		/* socket to send on */
-	/*
-	 * Function pointers for allocating memory.
-	 */
-	lwres_malloc_t	malloc;
-	lwres_free_t	free;
-	void		*arg;
-	/*
-	 * resolv.conf-like data
-	 */
-	lwres_conf_t	confdata;
-};
-
-typedef struct lwres_context lwres_context_t;
-.Ed
 .Sh DESCRIPTION
 .Fn lwres_context_create
-is used to create a
+creates a
 .Dv lwres_context_t
-structure for use in lightweight resolver operations and associate
-general purpose memory allocation functions with that structure.
-.Fa *contextp
-is a pointer to a
-.Dv "struct lwres_context" .
-It must be non-NULL, which in turn implies that
-.Fa **contextp
-is also non-NULL.
+structure for use in lightweight resolver operations.
+It holds a socket and other data needed for communicating
+with a resolver daemon.
+The new
+.Dv lwres_context_t
+is returned throught
+.Fa contextp ,
+a pointer to a
+.Dv "lwres_context_t"
+pointer.  This 
+.Dv "lwres_context_t"
+pointer must initially be NULL, and is modified 
+to point to the newly created
+.Dv "lwres_context_t" .
+.Pp
+When the lightweight resolver needs to perform dynamic memory
+allocation, it will call
+.Fa malloc_function
+to allocate memory and
+.Fa free_function 
+to free it.  If 
 .Fa malloc_function
 and
-.Fa free_function
-are pointers to the functions the context should use for allocating
-and freeing memory respectively.
-Both function pointers must either be non-NULL or NULL.
-It is not permitted to use a custom allocator - i.e
-.Fa malloc_function
-is non-NULL -
-with a NULL
-.Fa free_function
-or vice versa.
-If both function pointers are NULL, the lightweight resolver's
-internal allocation routines which call
+.Fa free_function 
+are NULL, memory is allocated using
 .Xr malloc 3
 and
-.Xr free 3
-are used.
+.Xr free 3 .
+It is not permitted to have a NULL
+.Fa malloc_function
+and a non-NULL
+.Fa free_function
+or vice versa.
 .Fa arg
-is passed as the initial parameter to the memory
-allocation functions.
-The argument is passed but not used in the internal allocation
-and deallocation routines.
+is passed as the first parameter to the memory
+allocation functions.  
+If
+.Fa malloc_function
+and
+.Fa free_function
+are NULL,
+.Fa arg 
+is unused and should be passed as NULL.
+.P
 Once memory for the structure has been allocated,
-.Xr lwres_conf_init 3
-is called to initialise it.
-The structure is then returned via
+it is initialized using
+.Xr lwres_conf_init 3 
+and returned via
 .Fa *contextp .
 .Pp
-A
-.Dv "struct lwres_context"
-is destroyed by
-.Fn lwres_context_destroy.
-.Fa **contextp
+.Fn lwres_context_destroy
+destroys a 
+.Dv "lwres_context_t" ,
+closing its socket.
+.Fa contextp
 is a pointer to a pointer to the context that is to be destroyed.
-It must be non-NULL, as should
-.Fa *contextp .
-If the context has an open socket, it is closed before the structure
-is discarded.
+The pointer will be set to NULL when the context has been destroyed.
 .Pp
-The context's serial number is controlled with
+The context holds a serial number that is used to identify resolver
+request packets and associate responses with the corresponding requests.
+This serial number is controlled using
 .Fn lwres_context_initserial
 and
 .Fn lwres_context_nextserial .
-Both require that
-.Fa ctx
-is not NULL.
 .Fn lwres_context_initserial
 sets the serial number for context
 .Fa *ctx
 to
 .Fa serial .
 .Fn lwres_context_nextserial
-returns the current serial number for the context and increments
-.Dv  ctx->serial .
+increments the serial number and returns the previous value.
 .Pp
 Memory for a lightweight resolver context is allocated and freed using
 .Fn lwres_context_allocmem
@@ -182,38 +168,16 @@ frees
 .Fa len
 bytes of space starting at location
 .Fa mem .
-It has assertion checks to ensure that
-.Fa mem
-is not null and
-.Fa len
-is not zero.
-.Pp
-If the lightweight resolver's memory allocation functions are used,
-.Fa len
-bytes in the allocated buffer will be set to '0xe5' on allocation
-or '0xa9' when they are freed.
 .Pp
 .Fn lwres_context_sendrecv
 performs I/O for the context
 .Fa ctx .
-Data are read and written from the context's socket
-.Dv ctx->sock .
+Data are read and written from the context's socket.
 It writes data from
 .Fa sendbase
-- typically a DNS query -
+- typically a lightweight resolver query packet -
 and waits for a reply which is copied to the receive buffer at
 .Fa recvbase .
-.Fa sendbase
-is a pointer to the
-.Fa sendlen
-bytes of data that are to be sent using
-.Xr sendto 2.
-Up to
-.Fn recvlen
-bytes of data that are returned by a call to
-.Xr recvfrom 2
-on the socket are copied to
-.Fa recvbase .
 The number of bytes that were written to this receive buffer is
 returned in
 .Fa *recvd_len .
@@ -223,9 +187,9 @@ returns
 .Er LWRES_R_NOMEMORY
 if memory for the
 .Dv "struct lwres_context"
-could not be allocated, otherwise
+could not be allocated, 
 .Er LWRES_R_SUCCESS
-is returned.
+otherwise.
 .Pp
 Successful calls to the memory allocator
 .Fn lwres_context_allocmem
@@ -239,18 +203,10 @@ completes successfully.
 .Er LWRES_R_IOERROR
 is returned if an I/O error occurs and
 .Er LWRES_R_TIMEOUT
-is returned if the
-.Xr recvfrom 2
-call times out.
+is returned if
+.Fn lwres_context_sendrecv
+times out waiting for a response.
 .Sh SEE ALSO
 .Xr lwres_conf_init 3 ,
 .Xr malloc 3 ,
-.Xr free 3 ,
-.Xr close 2 ,
-.Xr memset 3 ,
-.Xr sendto 2 ,
-.Xr recvfrom 2 .
-.Sh BUGS
-The
-.Dv lwres_context_t
-structures and the functions which operate on them are not thread-safe.
+.Xr free 3
diff --git a/lib/lwres/man/lwres_gabn.3 b/lib/lwres/man/lwres_gabn.3
index 4e0b353854..b5d6fc038e 100644
--- a/lib/lwres/man/lwres_gabn.3
+++ b/lib/lwres/man/lwres_gabn.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_gabn.3,v 1.3 2000/08/01 01:21:05 tale Exp $
+.\" $Id: lwres_gabn.3,v 1.4 2000/09/28 22:36:25 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GABN 3
@@ -26,7 +26,7 @@
 .Nm lwres_gabnresponse_parse ,
 .Nm lwres_gabnresponse_free ,
 .Nm lwres_gabnrequest_free
-.Nd lightweight resolver getaddrbyname functions
+.Nd lightweight resolver getaddrbyname message handling
 .Sh SYNOPSIS
 .Fd #include <lwres/lwres.h>
 .Fd
@@ -69,11 +69,10 @@
 .Fa "lwres_gabnrequest_t **structp"
 .Fc
 .Sh DESCRIPTION
-These functions implement the lightweight resolver's getaddrbyname opcode
-.Dv LWRES_OPCODE_GETADDRSBYNAME .
-They provide a forward lookup mechanism, mapping a hostname to its
-address or addresses.
-.Pp
+These are low-level routines for creating and parsing
+lightweight resolver name-to-address lookup request and 
+response messages.
+.P
 There are four main functions for the getaddrbyname opcode.
 One render function converts a getaddrbyname request structure -
 .Dv lwres_gabnrequest_t -
@@ -87,7 +86,7 @@ This is complemented by a parse function which converts a packet in
 canonical format to a getaddrbyname response structure.
 .Pp
 These structures are defined in
-.Pa lwres/lwres.h .
+.Pa <lwres/lwres.h> .
 They are shown below.
 .Bd -literal -offset indent
 #define LWRES_OPCODE_GETADDRSBYNAME	0x00010001U
diff --git a/lib/lwres/man/lwres_gai_strerror.3 b/lib/lwres/man/lwres_gai_strerror.3
index d36140f3c0..4d554eebbd 100644
--- a/lib/lwres/man/lwres_gai_strerror.3
+++ b/lib/lwres/man/lwres_gai_strerror.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_gai_strerror.3,v 1.3 2000/08/01 01:21:12 tale Exp $
+.\" $Id: lwres_gai_strerror.3,v 1.4 2000/09/28 22:36:26 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GAI_STRERROR 3
@@ -30,16 +30,11 @@
 .Fa "int ecode"
 .Fc
 .Sh DESCRIPTION
-.Fn gai_strerror
-returns a suitable error message for the error code
-.Fa ecode .
-The message \*qinvalid error code\*q is returned if
-.Fa ecode
-is out of range.
+.Fn lwres_gai_strerror
+returns an error message corresponding to an error code returned by
+.Fn getaddrinfo .
 The following error codes and their meaning are defined in
 .Aq Pa include/lwres/netdb.h .
-They can be returned by
-.Fn getaddrinfo .
 .Bl -tag -width EAI_ADDRFAMILY -offset indent -compact
 .It Dv EAI_ADDRFAMILY
 address family for hostname not supported
@@ -68,17 +63,20 @@ not supported
 .It Dv EAI_SYSTEM
 system error returned in errno
 .El
+The message \*qinvalid error code\*q is returned if
+.Fa ecode
+is out of range.
 .Pp
 .Li ai_flags ,
 .Li ai_family
 and
 .Li ai_socktype
 are elements of the
-.Dv "struct  addrinfo" used by
+.Dv "struct  addrinfo"
+used by
 .Fn lwres_getaddrinfo .
 .Sh SEE ALSO
-.Xr errno 2 ,
-.Xr perror 3 ,
+.Xr strerror 3 ,
 .Xr lwres_getaddrinfo 3 ,
 .Xr getaddrinfo 3 ,
 .Xr RFC2133 .
diff --git a/lib/lwres/man/lwres_getaddrinfo.3 b/lib/lwres/man/lwres_getaddrinfo.3
index 6039a1ff07..a0fc8c3946 100644
--- a/lib/lwres/man/lwres_getaddrinfo.3
+++ b/lib/lwres/man/lwres_getaddrinfo.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_getaddrinfo.3,v 1.3 2000/08/01 01:21:13 tale Exp $
+.\" $Id: lwres_getaddrinfo.3,v 1.4 2000/09/28 22:36:27 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GETADDRINFO 3
@@ -40,7 +40,8 @@
 .Pp
 If the operating system does not provide a
 .Dv "struct addrinfo" ,
-the following structure is used
+the following structure is used:
+.Pp
 .Bd -literal -offset indent
 struct	addrinfo {
 	int		ai_flags;	/* AI_PASSIVE, AI_CANONNAME */
@@ -58,7 +59,7 @@ struct	addrinfo {
 .Fn lwres_getaddrinfo
 is used to get a list of IP addresses and port numbers for host
 .Fa hostname
-and
+and service
 .Fa servname .
 The function is the lightweight resolver's implementation of
 .Fn getaddrinfo
@@ -66,12 +67,12 @@ as defined in RFC2133.
 .Fa hostname
 and
 .Fa servname
-arguments are pointers to null-terminated
+are pointers to null-terminated
 strings or
 .Dv NULL .
 .Fa hostname
-either a host name or a numeric host address string: a dotted decimal
-IPv4 address or an IPv6 hex address.
+is either a host name or a numeric host address string: a dotted decimal
+IPv4 address or an IPv6 address.
 .Fa servname
 is either a decimal port number or a service name as listed in
 .Pa /etc/services .
@@ -103,12 +104,13 @@ When
 .Li ai_socktype
 is zero the caller will accept any socket type.
 .It Li ai_protocol
-indicates which transport protocol is wanted: UDP or TCP.
+indicates which transport protocol is wanted: IPPROTO_UDP or 
+IPPROTO_TCP.
 If
 .Li ai_protocol
 is zero the caller will accept any protocol.
 .It Li ai_flags
-sets some flag bits.
+Flag bits.
 If the
 .Dv AI_CANONNAME
 bit is set, a successful call to
@@ -161,14 +163,9 @@ If
 is set to
 .Dv AI_NUMERICHOST
 it indicates that
-the
-.Dv non-NuLL
 .Fa hostname
-should be treated as a numeric string defining an IPv4 or IPv6 address.
-This will prevent a numeric IPv4 address from being considered as a domain
-name when
-.Fn lwres_getaddrinfo
-is looking for IPv6 addresses or vice versa.
+should be treated as a numeric string defining an IPv4 or IPv6 address
+and no name resolution should be attempted.
 .El
 .Pp
 All other elements of the
@@ -177,14 +174,13 @@ passed via
 .Fa arg
 must be zero.
 .Pp
-If
+An
 .Fa arg
-is not supplied, a
+of
 .Dv NULL
-pointer should be given for this argument.
-It will be treated as if the caller provided an
+is treated as if the caller provided a
 .Dv "struct addrinfo"
-structure initialized to zero with
+initialized to zero with
 .Li ai_family set to
 .Li PF_UNSPEC .
 .Pp
@@ -195,7 +191,8 @@ is a pointer to a linked list of one or more
 .Dv addrinfo
 structures.
 Each
-.Dv "struct addrinfo" in this list cn be processed by following
+.Dv "struct addrinfo" 
+in this list cn be processed by following
 the
 .Li ai_next
 pointer, until a
@@ -203,7 +200,7 @@ pointer, until a
 pointer is encountered.
 The three members
 .Li ai_family ,
-ai_socktype,
+.Li ai_socktype ,
 and
 .Li ai_protocol
 in each
@@ -230,7 +227,8 @@ is released by
 .Fn lwres_freeaddrinfo .
 .Fa ai
 is a pointer to a
-.Dv "struct addrinfo" created by a call to
+.Dv "struct addrinfo" 
+created by a call to
 .Fn lwres_getaddrinfo .
 .Sh RETURN VALUES
 .Fn lwres_getaddrinfo
@@ -247,13 +245,13 @@ are
 returns
 .Er EAI_NONAME .
 .Sh SEE ALSO
+.Xr lwres 3 ,
 .Xr lwres_getaddrinfo 3 ,
 .Xr lwres_freeaddrinfo 3 ,
 .Xr lwres_gai_strerror 3 ,
 .Xr RFC2133 ,
 .Xr getservbyname 3 ,
-.Xr bind 2
-.Xr connect 2
+.Xr bind 2 ,
 .Xr connect 2 ,
 .Xr sendto 2 ,
 .Xr sendmsg 2 ,
diff --git a/lib/lwres/man/lwres_gethostent.3 b/lib/lwres/man/lwres_gethostent.3
index c997d6f2e6..bca29524cf 100644
--- a/lib/lwres/man/lwres_gethostent.3
+++ b/lib/lwres/man/lwres_gethostent.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_gethostent.3,v 1.3 2000/08/01 01:21:21 tale Exp $
+.\" $Id: lwres_gethostent.3,v 1.4 2000/09/28 22:36:28 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GETHOSTENT 3
@@ -96,16 +96,15 @@
 .Fa "void"
 .Fc
 .Sh DESCRIPTION
-These functions define the interface to the lightweight resolver
-daemon \fPNOT IF IT IS GOING AWAY\fP
-for looking up hostnames and addresses. They are similar to the
-standard
+These functions provide hostname-to-address and
+address-to-hostname lookups by means of the lightweight resolver.
+They are similar to the standard
 .Xr gethostent 3
-functions provided by as part of the standard system software.
+functions provided by most operating systems.
 They use a
 .Dv "struct hostent"
 which is usually defined in
-.Pa namedb.h .
+.Pa <namedb.h> .
 .Bd -literal
 struct	hostent {
 	char	*h_name;	/* official name of host */
@@ -149,19 +148,17 @@ is the first address in
 .Fn lwres_sethostent_r
 and
 .Fn lwres_endhostent_r
-are empty stub functions which do nothing.
-They are provided as placeholders so that calls to the system's
-.Xr gethostent 3
-functions can simply be #defined to their
-.Xr lwres_res_gethost
-equivalents.
-See
-.Pa lwres/netdb.h .
+provide iteration over the known host entries on systems that
+provide such functionality through facilities like
+.Pa /etc/hosts
+or NIS.  The lightweight resolver does not currently implement
+these functions; it only provides them as stub functions that always
+return failure.
 .Pp
 .Fn lwres_gethostbyname
 and
 .Fn lwres_gethostbyname2
-lookup the hostname
+look up the hostname
 .Fa name .
 .Fn lwres_gethostbyname
 always looks for an IPv4 address while
@@ -173,9 +170,6 @@ either
 or
 .Dv PF_INET6
 - IPv4 or IPV6 addresses respectively.
-Both functions call
-.Fn lwres_getipnodebyname
-to look up the hostname.
 Successful calls of the functions return a
 .Dv "struct hostent" for
 the name that was looked up.
@@ -196,19 +190,9 @@ bytes and protocol family
 .Dv PF_INET
 or
 .Dv PF_INET6 .
-It calls
-.Fn lwres_getipnodebyaddr
-to do the reverse lookup.
-.Pp
 .Fn lwres_gethostbyname_r
 is a thread-safe function for forward lookups.
-It also calls
-.Fn lwres_getipnodebyname
-to lookup the hostname
-.Fa name .
-If
-.Fn lwres_getipnodebyname
-encounters an error, the error code is returned in
+If an error occurs, an error code is returned in
 .Fa *error .
 .Fa resbuf
 is a pointer to a
@@ -232,7 +216,7 @@ Successful calls to
 return
 .Fa resbuf ,
 which is a pointer to the
-.Fn "struct hostent"
+.Dv "struct hostent"
 it created.
 .Pp
 .Fn lwres_gethostbyaddr_r
@@ -246,13 +230,8 @@ and is of protocol family
 .Dv PF_INET
 or
 .Dv PF_INET6 .
-.Fn lwres_gethostbyaddr_r
-calls
-.Fn lwres_getipnodebyaddr
-to do the work.
-If this function encounters an error, the error code is returned in
+If an error occurs, the error code is returned in
 .Fa *error .
-Like
 The other function parameters are identical to those in
 .Fn lwres_gethostbyname_r .
 .Fa resbuf
@@ -287,36 +266,26 @@ The functions
 .Fn lwres_gethostbyaddr ,
 and
 .Fn lwres_gethostent
-are not thread-safe because they free any memory that had been allocated
-in a previous call to those functions before they perform a lookup.
-They also set the global variable
+return NULL to indicate an error.  In this case the global variable
 .Dv lwres_h_errno
-when they return.
-The values of this variable are defined in
-.Pa lwres/netdb.h .
-The values and their meaning are defined as follows:
+will contain one of the following error codes defined in
+.Pa <lwres/netdb.h> :
 .Bl -tag -width HOST_NOT_FOUND
-.It Li NETDB_INTERNAL
-Internal Error - see
-.Li errno
-.It Li NETDB_SUCCESS
-no problem
 .It Li HOST_NOT_FOUND
-Authoritative Answer Host not found
+The host or address was not found.
 .It Li TRY_AGAIN
-Non-Authoritive Answer Host not found, or
-.Dv SERVERFAIL
+A recoverable error occurred, e.g., a timeout.
+Retrying the lookup may succeed.
 .It Li NO_RECOVERY
-Non recoverable errors,
-.Dv FORMERR ,
-.Dv REFUSED ,
-or
-.Dv NOTIMP
+A non-recoverable error occurred.
 .It Li NO_DATA
-Valid name, but no data record of requested type
-.It Li NO_ADDRESS
-no address, so look for MX record
+The name exists, but has no address information
+associated with it (or vice versa in the case
+of a reverse lookup).  The code NO_ADDRESS
+is accepted as a synonym for NO_DATA for backwards
+compatibility.
 .El
+.Pp
 .Xr lwres_hstrerror 3
 translates these error codes to suitable error messages.
 .Pp
@@ -355,7 +324,7 @@ was too small, both
 and
 .Fn lwres_gethostbyaddr_r
 set the global variable
-.DV errno
+.Dv errno
 to
 .Er ERANGE .
 .Sh SEE ALSO
@@ -363,26 +332,13 @@ to
 .Xr lwres_getipnode 3 ,
 .Xr lwres_hstrerror 3
 .Sh BUGS
-Although
 .Fn lwres_gethostbyname ,
 .Fn lwres_gethostbyname2 ,
 .Fn lwres_gethostbyaddr
 and
 .Fn lwres_endhostent
-call thread-safe functions to perform lookups, these 3 functions
-are not thread-safe because they set the global variable
-.Dv lwres_h_errno
-which could
-overwritten if two or more threads called these functions
-simultaneously.
-They also release any memory that had been allocated in a previous call
-to these functions.
-This emulates the semantics of their equivalent functions in the
-system's
-.Xr gethostent 3
-functions which use a static buffer that gets overwritten in subsequent
-calls to those routines.
-.Pp
+are not thread safe; they return pointers to static data and 
+provide error codes through a global variable.
 Thread-safe versions for name and address lookup are provided by
 .Fn lwres_gethostbyname_r ,
 and
diff --git a/lib/lwres/man/lwres_getipnode.3 b/lib/lwres/man/lwres_getipnode.3
index ff4b80c902..73f2b3537b 100644
--- a/lib/lwres/man/lwres_getipnode.3
+++ b/lib/lwres/man/lwres_getipnode.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_getipnode.3,v 1.3 2000/08/01 01:21:24 tale Exp $
+.\" $Id: lwres_getipnode.3,v 1.4 2000/09/28 22:36:29 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GETIPNODE 3
@@ -23,9 +23,9 @@
 .Nm lwres_getipnodebyname ,
 .Nm lwres_getipnodebyaddr ,
 .Nm lwres_freehostent
-.Nd lookup functions for the lightweight resolver
+.Nd lightweight resolver nodename / address translation API
 .Sh SYNOPSIS
-.Fd #include <lwres/lwres.h>
+.Fd #include <lwres/netdb.h>
 .Fd
 .Ft struct hostent *
 .Fo lwres_getipnodebyname
@@ -46,10 +46,14 @@
 .Fa "struct hostent *he"
 .Fc
 .Sh DESCRIPTION
-These functions use a
+These functions perform thread safe, protocol independent
+nodename-to-address and address-to-nodename 
+translation as defined in RFC2553.
+.Pp
+They use a
 .Dv "struct hostent"
-which is usually defined in
-.Pa namedb.h .
+which is defined in
+.Pa namedb.h :
 .Bd -literal
 struct	hostent {
 	char	*h_name;	/* official name of host */
@@ -68,7 +72,7 @@ The official (canonical) name of the host.
 .It Li h_aliases
 A NULL-terminated array of alternate names (nicknames) for the host.
 .It Li h_addrtype
-The type of address being returned -
+The type of address being returned - usually
 .Dv PF_INET
 or
 .Dv PF_INET6 .
@@ -81,92 +85,53 @@ terminated array of network addresses for the host.
 Host addresses are returned in network byte order.
 .El
 .Pp
-For backward compatibility with very old software,
-.Li h_addr
-is the first address in
-.Li h_addr_list.
-.Pp
 .Fn lwres_getipnodebyname
-looks up the hostname
-.Fa name
-of protocol family
-.Fa af .
+looks up addresses of protocol family
+.Fa af 
+for the hostname
+.Fa name .
 The
 .Fa flags
-parameter sets bits that indicate how IPv6 and IPv4 addresses
-should presented.
-The value of those flags are:
+parameter contains ORed flag bits to 
+specify the types of addresses that are searched
+for, and the types of addresses that are returned. 
+The flag bits are:
 .Bl -tag -width AI_ADDRCONFIG
 .It Li AI_V4MAPPED
-return an IPv4 address mapped to an IPv6 address
+This is used with an
+.Fa af
+of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
+IPv6 addresses.
 .It Li AI_ALL
-return all possible addresses
+This is used with an
+.Fa af
+of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
+If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
+IPv6 addresses.
 .It Li AI_ADDRCONFIG
-only return an IPv6 or IPv4 address if here is an active network
-interface of that type.
+Only return an IPv6 or IPv4 address if here is an active network
+interface of that type.  This is not currently implemented
+in the BIND 9 lightweight resolver, and the flag is ignored.
 .It Li AI_DEFAULT
-this default sets the
+This default sets the
 .Li AI_V4MAPPED
 and
 .Li AI_ADDRCONFIG
 flag bits.
 .El
 .Pp
-The value of
-.Dv AF_INET6
-is sometimes added to
-.Fa flags .
-When
-.Fa flags
-is set to
-.Li "AI_V4MAPPED + AF_INET6"
-.Fn lwres_getipnodebyname
-will look for an IPv6 address and if this is not found it will look
-for an IPv4 address and map it to an IPv6 address.
-When
-.Fa flags
-is
-.Li "AI_ALL + AI_V4MAPPED + AF_INET6" ,
-.Fn lwres_getipnodebyname
-returns mapped IPv4 addresses and IPv6 addresses.
-.Fn lwres_getipnodebyname
-calls
-.Fn lwres_context_create
-to create a resolver context for the lookup and
-then calls
-.Fn lwres_getaddrsbyname
-to lookup the name using that resolver context.
-.Pp
 .Fn lwres_getipnodebyaddr
-performs a thread-safe reverse lookup
+performs a reverse lookup
 of address
 .Fa src
 which is
 .Fa len
 bytes long.
 .Fa af
-denotes the protocol family:
+denotes the protocol family, typically
 .Dv PF_INET
 or
 .Dv PF_INET6 .
-.Fn lwres_getipnodebyaddr
-also sets up a resolver context by calling
-.Fn lwres_context_create.
-It then calls
-.Fn lwres_getnamebyaddr
-to make the query.
-.Pp
-Both
-.Fn lwres_getipnodebyname
-and
-.Fn lwres_getipnodebyaddr
-will free any memory that was allocated during intermediate stages of the
-lookup by calling
-.Fn lwres_gnbaresponse_free .
-Both functions call
-.Fn lwres_getipnodebyaddr
-immediately before they return so that the created resolver context
-gets discarded.
 .Pp
 .Fn lwres_freehostent
 releases all the memory associated with
@@ -193,37 +158,29 @@ to an approriate error code and the function returns a
 .Dv NULL
 pointer.
 The error codes and their meanings are defined in
-.Pa lwres/netdb.h .
+.Pa <lwres/netdb.h> :
 .Bl -tag -width HOST_NOT_FOUND
-.It Li NETDB_INTERNAL
-Internal Error - see
-.Li errno
-.It Li NETDB_SUCCESS
-no problem
 .It Li HOST_NOT_FOUND
-Authoritative Answer Host not found
-.It Li TRY_AGAIN
-Non-Authoritive Answer Host not found, or
-.Dv SERVERFAIL
-.It Li NO_RECOVERY
-Non recoverable errors,
-.Dv FORMERR ,
-.Dv REFUSED ,
-or
-.Dv NOTIMP
-.It Li NO_DATA
-Valid name, but no data record of requested type
+No such host is known.
 .It Li NO_ADDRESS
-no address, so look for MX record
+The server recognised the request and the name but no address is
+available.  Another type of request to the name server for the
+domain might return an answer.
+.It Li TRY_AGAIN
+A temporary and possibly transient error occurred, such as a
+failure of a server to respond.  The request may succeed if
+retried.
+.It Li NO_RECOVERY
+An unexpected failure occurred, and retrying the request
+is pointless.
 .El
 .Pp
 .Xr lwres_hstrerror 3
 translates these error codes to suitable error messages.
 .Sh SEE ALSO
-.Xr lwres_res_getaddrsbyname 3 ,
-.Xr lwres_res_context_create 3 ,
-.Xr lwres_res_context_destroy 3 ,
-.Xr lwres_res_gnbaresponse_free 3 ,
-.Xr lwres_res_getaddrsbyaddr 3 ,
-.Xr free 3 ,
+.Xr RFC2553 ,
+.Xr lwres 3 ,
+.Xr lwres_gethostent 3 ,
+.Xr lwres_getaddrinfo 3 ,
+.Xr lwres_getnameinfo 3 ,
 .Xr lwres_hstrerror 3 .
diff --git a/lib/lwres/man/lwres_getnameinfo.3 b/lib/lwres/man/lwres_getnameinfo.3
index c7e8986735..0c4c498baf 100644
--- a/lib/lwres/man/lwres_getnameinfo.3
+++ b/lib/lwres/man/lwres_getnameinfo.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_getnameinfo.3,v 1.4 2000/08/01 01:21:28 tale Exp $
+.\" $Id: lwres_getnameinfo.3,v 1.5 2000/09/28 22:36:30 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GETNAMEINFO 3
@@ -23,7 +23,7 @@
 .Nm lwres_getnameinfo
 .Nd lightweight resolver socket address structure to hostname and service name
 .Sh SYNOPSIS
-.Fd #include <lwres/lwres.h>
+.Fd #include <lwres/netdb.h>
 .Fd
 .Ft int
 .Fo lwres_getnameinfo
@@ -64,50 +64,33 @@ It is
 bytes long.
 The maximum length of the service name is
 .Li NI_MAXSERV
-- 32 - bytes.
+- 32 bytes.
 .Pp
 The
 .Fa flags
 argument sets the following bits:
 .Bl -tag -width NI_NUMERICSERV
 .It Li NI_NOFQDN
-a fully qualified domain name is not required for local hosts.
+A fully qualified domain name is not required for local hosts.
 The local part of the fully qualified domain name is returned instead.
 .It Li NI_NUMERICHOST
-the address in the
-.Dv sockaddr
-structure is presented as a dotted-decimal string for an IPv4
-address or an IPv6 hex address if the hostname is not found in the
-DNS.
+Return the address in numeric form, as if calling inet_ntop(),
+instead of a host name.
 .It Li NI_NAMEREQD
-a name is required. If the hostname cannot be found in the DNS and
-this flag is set, a non-zero error code
-is returned.
+A name is required. If the hostname cannot be found in the DNS and
+this flag is set, a non-zero error code is returned.
+If the hostname is not found and the flag is not set, the 
+address is returned in numeric form.
 .It Li NI_NUMERICSERV
-service name is returned as a digit string representing the port number.
+The service name is returned as a digit string representing the port number.
 .It Li NI_DGRAM
-the service uses a datagram transport protocol
+Specifies that the service being looked up is a datagram
+service,  and causes getservbyport() to be called with a second
+argument of "udp" instead of its default of "tcp".  This is required
+for the few ports (512-514) that have different services for UDP and
+TCP.
 .El
 .Pp
-When a numeric host address string is needed,
-.Fn lwres_getnameinfo
-calls
-.Fn lwres_net_ntop
-to generate an IPv6 hex address or a dotted decimal IPv4 address.
-If required,
-.Fn lwres_getnameinfo
-will create a resolver context by calling
-.Fn lwres_context_create
-and then using
-.Fn lwres_getnamebyaddr
-to perform the reverse lookup.
-Any memory allocated during that reverse lookup will be
-freed by calling
-.Fn lwres_gnbaresponse_free .
-.Fn lwres_context_destroy
-is called immediately before
-.Fn lwres_getnameinfo
-returns so that the created resolver context gets discarded.
 .Sh RETURN VALUES
 .Fn lwres_getnameinfo
 returns 0 on success or a non-zero error code if an error occurs.
@@ -135,12 +118,13 @@ returns 0 on success or a non-zero error code if an error occurs.
 .\" is the wrong number of bytes for the address in
 .\" Fa sa .
 .Sh SEE ALSO
-.Xr getnameinfo 3 ,
 .Xr RFC2133 ,
 .Xr getservbyport 3 ,
-.Xr lwres_res_net_ntop 3 ,
-.Xr lwres_res_context_create 3,
-.Xr lwres_res_getnamebyaddr 3,
-.Xr lwres_res_gnbaresponse_free 3 ,
-.Xr lwres_res_context_destroy 3 ,
-.Xr lwres_res_net_ntop 3 .
+.Xr lwres 3 ,
+.Xr lwres_getnameinfo 3 ,
+.Xr lwres_getnamebyaddr 3,
+.Xr lwres_net_ntop 3 .
+.Sh BUGS
+RFC2133 fails to define what the nonzero return values of
+.Xr getnameinfo 3 
+are.
diff --git a/lib/lwres/man/lwres_gnba.3 b/lib/lwres/man/lwres_gnba.3
index d25661261b..d08213b6ef 100644
--- a/lib/lwres/man/lwres_gnba.3
+++ b/lib/lwres/man/lwres_gnba.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_gnba.3,v 1.3 2000/08/01 01:21:29 tale Exp $
+.\" $Id: lwres_gnba.3,v 1.4 2000/09/28 22:36:31 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_GNBA 3
@@ -26,7 +26,7 @@
 .Nm lwres_gnbaresponse_parse ,
 .Nm lwres_gnbaresponse_free ,
 .Nm lwres_gnbarequest_free
-.Nd lightweight resolver getnamebyaddress functions
+.Nd lightweight resolver getnamebyaddress message handling
 .Sh SYNOPSIS
 .Fd #include <lwres/lwres.h>
 .Fd
@@ -69,10 +69,9 @@
 .Fa "lwres_gnbarequest_t **structp"
 .Fc
 .Sh DESCRIPTION
-These functions implement the lightweight resolver's getnamebyaddr opcode
-.Dv LWRES_OPCODE_GETNAMEBYADDR .
-They provide a reverse lookup mechanism, mapping an address to its
-hostname.
+These are low-level routines for creating and parsing
+lightweight resolver address-to-name lookup request and 
+response messages.
 .Pp
 There are four main functions for the getnamebyaddr opcode.
 One render function converts a getnamebyaddr request structure -
diff --git a/lib/lwres/man/lwres_noop.3 b/lib/lwres/man/lwres_noop.3
index 3846f41bd1..5d779818dc 100644
--- a/lib/lwres/man/lwres_noop.3
+++ b/lib/lwres/man/lwres_noop.3
@@ -13,7 +13,7 @@
 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" $Id: lwres_noop.3,v 1.3 2000/08/01 01:21:48 tale Exp $
+.\" $Id: lwres_noop.3,v 1.4 2000/09/28 22:36:33 gson Exp $
 .\"
 .Dd Jun 30, 2000
 .Dt LWRES_NOOP 3
@@ -26,7 +26,7 @@
 .Nm lwres_noopresponse_parse ,
 .Nm lwres_noopresponse_free ,
 .Nm lwres_nooprequest_free
-.Nd lightweight resolver no-op functions
+.Nd lightweight resolver no-op message handling
 .Sh SYNOPSIS
 .Fd #include <lwres/lwres.h>
 .Fd
@@ -69,10 +69,11 @@
 .Fa "lwres_nooprequest_t **structp"
 .Fc
 .Sh DESCRIPTION
-These functions implement the lightweight resolver's no-op opcode
-.Dv LWRES_OPCODE_NOOP .
-This is analogous to a \*qping\*q test: a packet is sent to the
-lightweight resolver daemon and is simply echoed back.
+These are low-level routines for creating and parsing
+lightweight resolver no-op request and response messages.
+.P
+The no-op message is analogous to a \*qping\*q packet: 
+a packet is sent to the resolver daemon and is simply echoed back.
 The opcode is intended to allow a client to determine if the server is
 operational or not.
 .Pp