1 files changed, 294 insertions, 0 deletions
diff --git a/doc/man/lwres/lwres_buffer.3 b/doc/man/lwres/lwres_buffer.3
new file mode 100644
index 00000000..d5b9f1b4
--- /dev/null
+++ b/doc/man/lwres/lwres_buffer.3
@@ -0,0 +1,294 @@
+.\" Copyright (C) 2000  Internet Software Consortium.
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
+.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
+.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
+.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
+.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+.\" 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.5 2000/11/18 02:59:15 bwelling Exp $
+
+.Dd Jun 30, 2000
+.Dt LWRES_BUFFER 3
+.Os BIND9 9
+.ds vT BIND9 Programmer's Manual
+.Sh NAME
+.Nm lwres_buffer_init ,
+.Nm lwres_buffer_invalidate ,
+.Nm lwres_buffer_add ,
+.Nm lwres_buffer_subtract ,
+.Nm lwres_buffer_clear ,
+.Nm lwres_buffer_first ,
+.Nm lwres_buffer_forward ,
+.Nm lwres_buffer_back ,
+.Nm lwres_buffer_getuint8 ,
+.Nm lwres_buffer_putuint8 ,
+.Nm lwres_buffer_getuint16 ,
+.Nm lwres_buffer_putuint16 ,
+.Nm lwres_buffer_getuint32 ,
+.Nm lwres_buffer_putuint32 ,
+.Nm lwres_buffer_putmem ,
+.Nm lwres_buffer_getmem
+.Nd lightweight resolver buffer management
+.Sh SYNOPSIS
+.Fd #include <lwres/lwbuffer.h>
+.Fd
+.Ft void
+.Fo lwres_buffer_init
+.Fa "lwres_buffer_t *b"
+.Fa "void *base"
+.Fa "unsigned int length"
+.Fc
+.Ft void
+.Fo lwres_buffer_invalidate
+.Fa "lwres_buffer_t *b"
+.Fc
+.Ft void
+.Fo lwres_buffer_add
+.Fa "lwres_buffer_t *b"
+.Fa "unsigned int n"
+.Fc
+.Ft void
+.Fo lwres_buffer_subtract
+.Fa "lwres_buffer_t *b"
+.Fa "unsigned int n"
+.Fc
+.Ft void
+.Fo lwres_buffer_clear
+.Fa "lwres_buffer_t *b"
+.Fc
+.Ft void
+.Fo lwres_buffer_first
+.Fa "lwres_buffer_t *b"
+.Fc
+.Ft void
+.Fo lwres_buffer_forward
+.Fa "lwres_buffer_t *b"
+.Fa "unsigned int n"
+.Fc
+.Ft void
+.Fo lwres_buffer_back
+.Fa "lwres_buffer_t *b"
+.Fa "unsigned int n"
+.Fc
+.Ft lwres_uint8_t
+.Fo lwres_buffer_getuint8
+.Fa "lwres_buffer_t *b"
+.Fc
+.Ft void
+.Fo lwres_buffer_putuint8
+.Fa "lwres_buffer_t *b"
+.Fa "lwres_uint8_t val"
+.Fc
+.Ft lwres_uint16_t
+.Fo lwres_buffer_getuint16
+.Fa "lwres_buffer_t *b"
+.Fc
+.Ft void
+.Fo lwres_buffer_putuint16
+.Fa "lwres_buffer_t *b"
+.Fa "lwres_uint16_t val"
+.Fc
+.Ft lwres_uint32_t
+.Fo lwres_buffer_getuint32
+.Fa "lwres_buffer_t *b"
+.Fc
+.Ft void
+.Fo lwres_buffer_putuint32
+.Fa "lwres_buffer_t *b"
+.Fa "lwres_uint32_t val"
+.Fc
+.Ft void
+.Fo lwres_buffer_putmem
+.Fa "lwres_buffer_t *b"
+.Fa "const unsigned char *base"
+.Fa "unsigned int length"
+.Fc
+.Ft void
+.Fo lwres_buffer_getmem
+.Fa "lwres_buffer_t *b"
+.Fa "unsigned char *base"
+.Fa "unsigned int length"
+.Fc
+.Sh DESCRIPTION
+
+
+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.
+The \*qused region\*q and the \*qavailable\*q region are disjoint, and
+their union is the buffer's region.
+The used region extends from the beginning of the buffer region to the
+last used byte.
+The available region extends from one byte greater than the last used
+byte to the end of the  buffer's region.
+The size of the used region can be changed using various
+buffer commands.
+Initially, the used region is empty.
+.Pp
+The used region is further subdivided into two disjoint regions: the
+\*qconsumed region\*q and the \*qremaining region\*q.
+The union of these two regions is the used region.
+The consumed region extends from the beginning of the used region to
+the byte before the \*qcurrent\*q offset (if any).
+The \*qremaining\*q region the current pointer to the end of the used
+region.
+The size of the consumed region can be changed using various
+buffer commands.
+Initially, the consumed region is empty.
+.Pp
+The \*qactive region\*q is an (optional) subregion of the remaining
+region.
+It extends from the current offset to an offset in the
+remaining region.
+Initially, the active region is empty.
+If the current offset advances beyond the chosen offset,
+the active region will also be empty.
+.Pp
+.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
+initializes the
+.Dv lwres_buffer_t
+.Fa *b
+and assocates it with the memory region of size
+.Fa length
+bytes starting at location
+.Fa base.
+.Pp
+.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
+and
+.Fn lwres_buffer_subtract
+respectively increase and decrease the used space in
+buffer
+.Fa *b
+by
+.Fa n
+bytes.
+.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 used .
+.Pp
+A buffer is re-initialised by
+.Fn lwres_buffer_clear .
+The function sets
+.Li used ,
+.Li current
+and
+.Li active
+to zero.
+.Pp
+.Fn lwres_buffer_first
+makes the consumed region of buffer
+.Fa *p
+empty by setting
+.Li current
+to zero (the start of the buffer).
+.Pp
+.Fn lwres_buffer_forward 
+increases the consumed region of buffer
+.Fa *b
+by
+.Fa n
+bytes, checking for overflow.
+Similarly,
+.Fn lwres_buffer_back
+decreases buffer
+.Fa b 's
+consumed region by
+.Fa n
+bytes and checks for underflow.
+.Pp
+.Fn lwres_buffer_getuint8
+reads an unsigned 8-bit integer from
+.Fa *b
+and returns it.
+.Fn lwres_buffer_putuint8
+writes the unsigned 8-bit integer
+.Fa val
+to buffer
+.Fa *b .
+.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 
+in network byte order from
+.Fa b .
+Similarly,
+.Fn lwres_buffer_putuint16
+and
+.Fn lwres_buffer_putuint32
+writes the unsigned 16-bit or 32-bit integer
+.Fa val
+to buffer
+.Fa b ,
+in network byte order.
+.Pp
+Arbitrary amounts of data are read or written from a lightweight
+resolver buffer with
+.Fn lwres_buffer_getmem
+and
+.Fn lwres_buffer_putmem
+respectively.
+.Fn lwres_buffer_putmem
+copies
+.Fa length
+bytes of memory at
+.Fa base
+to
+.Fa b.
+Conversely,
+.Fn lwres_buffer_getmem
+copies
+.Fa length
+bytes of memory from
+.Fa b
+to
+.Fa base .
+.Sh SEE ALSO