first cut at mandoc -> docbook conversion

diff --git a/lib/lwres/man/lwres_buffer.docbook b/lib/lwres/man/lwres_buffer.docbook
new file mode 100644 (file)
index 0000000..37bf0f6
--- /dev/null
+++ b/lib/lwres/man/lwres_buffer.docbook
@@ -0,0 +1,378 @@
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+<!--
+ - Copyright (C) 2000, 2001  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.docbook,v 1.1 2001/03/29 02:23:11 gson Exp $ -->
+
+<refentry>
+  <refentryinfo>
+<date>Jun 30, 2000</date>
+</refentryinfo>
+
+<refmeta>
+    <refentrytitle>lwres_buffer</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo>BIND9</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>lwres_buffer_init</refname>
+<refname>lwres_buffer_invalidate</refname>
+<refname>lwres_buffer_add</refname>
+<refname>lwres_buffer_subtract</refname>
+<refname>lwres_buffer_clear</refname>
+<refname>lwres_buffer_first</refname>
+<refname>lwres_buffer_forward</refname>
+<refname>lwres_buffer_back</refname>
+<refname>lwres_buffer_getuint8</refname>
+<refname>lwres_buffer_putuint8</refname>
+<refname>lwres_buffer_getuint16</refname>
+<refname>lwres_buffer_putuint16</refname>
+<refname>lwres_buffer_getuint32</refname>
+<refname>lwres_buffer_putuint32</refname>
+<refname>lwres_buffer_putmem</refname>
+<refname>lwres_buffer_getmem</refname>
+<refpurpose>lightweight resolver buffer management</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+
+<funcsynopsis>
+<funcsynopsisinfo>
+#include &lt;lwres/lwbuffer.h&gt;
+</funcsynopsisinfo>
+
+<funcprototype>
+
+<funcdef>
+void
+<function>lwres_buffer_init</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>void *base</paramdef>
+<paramdef>unsigned int length</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+void
+<function>lwres_buffer_invalidate</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>
+void
+<function>lwres_buffer_add</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>unsigned int n</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+void
+<function>lwres_buffer_subtract</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>unsigned int n</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+void
+<function>lwres_buffer_clear</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+void
+<function>lwres_buffer_first</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+void
+<function>lwres_buffer_forward</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>unsigned int n</paramdef>
+</funcprototype>
+<funcprototype>
+
+<funcdef>
+void
+<function>lwres_buffer_back</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>unsigned int n</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+lwres_uint8_t
+<function>lwres_buffer_getuint8</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+void
+<function>lwres_buffer_putuint8</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>lwres_uint8_t val</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+lwres_uint16_t
+<function>lwres_buffer_getuint16</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+void
+<function>lwres_buffer_putuint16</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>lwres_uint16_t val</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+lwres_uint32_t
+<function>lwres_buffer_getuint32</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+void
+<function>lwres_buffer_putuint32</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>lwres_uint32_t val</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+void
+<function>lwres_buffer_putmem</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>const unsigned char *base</paramdef>
+<paramdef>unsigned int length</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+void
+<function>lwres_buffer_getmem</function></funcdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>unsigned char *base</paramdef>
+<paramdef>unsigned int length</paramdef>
+</funcprototype>
+
+</funcsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+
+<title>DESCRIPTION</title>
+<para>
+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
+<literal>isc_buffer_</literal>
+functions in the ISC library.
+</para>
+<para>
+A buffer is a region of memory, together with a set of related
+subregions.
+The <emphasis>used region</emphasis> and the
+<emphasis>available</emphasis> 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.
+</para>
+<para>
+The used region is further subdivided into two disjoint regions: the
+<emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
+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 <emphasis>current</emphasis> offset (if any).
+The <emphasis>remaining</emphasis> 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.
+</para>
+<para>
+The <emphasis>active region</emphasis> 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.
+</para>
+<para>
+<programlisting>
+ 
+   /------------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.
+</programlisting>
+</para>
+<para>
+<function>lwres_buffer_init()</function>
+initializes the
+<type>lwres_buffer_t</type>
+<parameter>*b</parameter>
+and assocates it with the memory region of size
+<parameter>length</parameter>
+bytes starting at location
+<parameter>base.</parameter>
+</para>
+<para>
+<function>lwres_buffer_invalidate()</function>
+marks the buffer
+<parameter>*b</parameter>
+as invalid.  Invalidating a buffer after use is not required,
+but makes it possible to catch its possible accidental use.
+</para>
+<para>
+The functions
+<function>lwres_buffer_add()</function>
+and
+<function>lwres_buffer_subtract()</function>
+respectively increase and decrease the used space in
+buffer
+<parameter>*b</parameter>
+by
+<parameter>n</parameter>
+bytes.
+<function>lwres_buffer_add()</function>
+checks for buffer overflow and
+<function>lwres_buffer_subtract()</function>
+checks for underflow.
+These functions do not allocate or deallocate memory.
+They just change the value of
+<structfield>used</structfield>.
+</para>
+<para>
+A buffer is re-initialised by
+<function>lwres_buffer_clear()</function>.
+The function sets
+<structfield>used</structfield> ,
+<structfield>current</structfield>
+and
+<structfield>active</structfield>
+to zero.
+</para>
+<para>
+<function>lwres_buffer_first</function>
+makes the consumed region of buffer
+<parameter>*p</parameter>
+empty by setting
+<structfield>current</structfield>
+to zero (the start of the buffer).
+</para>
+<para>
+<function>lwres_buffer_forward()</function>
+increases the consumed region of buffer
+<parameter>*b</parameter>
+by
+<parameter>n</parameter>
+bytes, checking for overflow.
+Similarly,
+<function>lwres_buffer_back()</function>
+decreases buffer
+<parameter>b</parameter>'s
+consumed region by
+<parameter>n</parameter>
+bytes and checks for underflow.
+</para>
+<para>
+<function>lwres_buffer_getuint8()</function>
+reads an unsigned 8-bit integer from
+<parameter>*b</parameter>
+and returns it.
+<function>lwres_buffer_putuint8()</function>
+writes the unsigned 8-bit integer
+<parameter>val</parameter>
+to buffer
+<parameter>*b</parameter>.
+</para>
+<para>
+<function>lwres_buffer_getuint16()</function>
+and
+<function>lwres_buffer_getuint32()</function>
+are identical to
+<function>lwres_buffer_putuint8()</function>
+except that they respectively read an unsigned 16-bit or 32-bit integer 
+in network byte order from
+<parameter>b</parameter>.
+Similarly,
+<function>lwres_buffer_putuint16()</function>
+and
+<function>lwres_buffer_putuint32()</function>
+writes the unsigned 16-bit or 32-bit integer
+<parameter>val</parameter>
+to buffer
+<parameter>b</parameter>,
+in network byte order.
+</para>
+<para>
+Arbitrary amounts of data are read or written from a lightweight
+resolver buffer with
+<function>lwres_buffer_getmem()</function>
+and
+<function>lwres_buffer_putmem()</function>
+respectively.
+<function>lwres_buffer_putmem()</function>
+copies
+<parameter>length</parameter>
+bytes of memory at
+<parameter>base</parameter>
+to
+<parameter>b</parameter>.
+Conversely,
+<function>lwres_buffer_getmem()</function>
+copies
+<parameter>length</parameter>
+bytes of memory from
+<parameter>b</parameter>
+to
+<parameter>base</parameter>.
+</para>
+</refsect1>
+</refentry>

diff --git a/lib/lwres/man/lwres_gnba.docbook b/lib/lwres/man/lwres_gnba.docbook
new file mode 100644 (file)
index 0000000..e98bab9
--- /dev/null
+++ b/lib/lwres/man/lwres_gnba.docbook
@@ -0,0 +1,258 @@
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+<!--
+ - Copyright (C) 2000, 2001  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_gnba.docbook,v 1.1 2001/03/29 02:23:11 gson Exp $ -->
+
+<refentry>
+
+<refentryinfo>
+<date>Jun 30, 2000</date>
+</refentryinfo>
+
+  <refmeta>
+    <refentrytitle>lwres_gnba</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo>BIND9</refmiscinfo>
+  </refmeta>
+
+<refnamediv>
+<refname>lwres_gnbarequest_render</refname>
+<refname>lwres_gnbaresponse_render</refname>
+<refname>lwres_gnbarequest_parse</refname>
+<refname>lwres_gnbaresponse_parse</refname>
+<refname>lwres_gnbaresponse_free</refname>
+<refname>lwres_gnbarequest_free</refname>
+<refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+
+<funcsynopsis>
+<funcsynopsisinfo>
+#include &lt;lwres/lwres.h&gt;
+</funcsynopsisinfo>
+
+<funcprototype>
+<funcdef>
+lwres_result_t
+<function>lwres_gnbarequest_render</function>
+</funcdef>
+<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+<paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef>
+<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
+<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+lwres_result_t
+<function>lwres_gnbaresponse_render</function>
+</funcdef>
+<paramdef>lwres_context_t *ctx</paramdef>
+<paramdef>lwres_gnbaresponse_t *req</paramdef>
+<paramdef>lwres_lwpacket_t *pkt</paramdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>
+lwres_result_t
+<function>lwres_gnbarequest_parse</function></funcdef>
+<paramdef>lwres_context_t *ctx</paramdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>lwres_lwpacket_t *pkt</paramdef>
+<paramdef>lwres_gnbarequest_t **structp</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>
+lwres_result_t
+<function>lwres_gnbaresponse_parse</function></funcdef>
+<paramdef>lwres_context_t *ctx</paramdef>
+<paramdef>lwres_buffer_t *b</paramdef>
+<paramdef>lwres_lwpacket_t *pkt</paramdef>
+<paramdef>lwres_gnbaresponse_t **structp</paramdef>
+</funcprototype>
+
+<funcprototype>
+<funcdef>
+void
+<function>lwres_gnbaresponse_free</function>
+</funcdef>
+<paramdef>lwres_context_t *ctx</paramdef>
+<paramdef>lwres_gnbaresponse_t **structp</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>
+void
+<function>lwres_gnbarequest_free</function></funcdef>
+<paramdef>lwres_context_t *ctx</paramdef>
+<paramdef>lwres_gnbarequest_t **structp</paramdef>
+</funcprototype>
+</funcsynopsis>
+
+</refsynopsisdiv>
+
+<refsect1>
+<title>DESCRIPTION</title>
+<para>
+These are low-level routines for creating and parsing
+lightweight resolver address-to-name lookup request and 
+response messages.
+</para>
+<para>
+There are four main functions for the getnamebyaddr opcode.
+One render function converts a getnamebyaddr request structure -
+<type>lwres_gnbarequest_t</type> -
+to the lightweight resolver's canonical format.
+It is complemented by a parse function that converts a packet in this
+canonical format to a getnamebyaddr request structure.
+Another render function converts the getnamebyaddr response structure -
+<type>lwres_gnbaresponse_t</type>
+to the canonical format.
+This is complemented by a parse function which converts a packet in
+canonical format to a getnamebyaddr response structure.
+</para>
+<para>
+These structures are defined in
+<filename>lwres/lwres.h</filename>.
+They are shown below.
+<programlisting>
+#define LWRES_OPCODE_GETNAMEBYADDR     0x00010002U
+
+typedef struct {
+       lwres_uint32_t  flags;
+       lwres_addr_t    addr;
+} lwres_gnbarequest_t;
+
+typedef struct {
+       lwres_uint32_t  flags;
+       lwres_uint16_t  naliases;
+       char           *realname;
+       char          **aliases;
+       lwres_uint16_t  realnamelen;
+       lwres_uint16_t *aliaslen;
+       void           *base;
+       size_t          baselen;
+} lwres_gnbaresponse_t;
+</programlisting>
+</para>
+<para>
+<function>lwres_gnbarequest_render()</function>
+uses resolver context
+<varname>ctx</varname>
+to convert getnamebyaddr request structure
+<varname>req</varname>
+to canonical format.
+The packet header structure
+<varname>pkt</varname>
+is initialised and transferred to
+buffer
+<varname>b</varname>.
+The contents of
+<varname>*req</varname>
+are then appended to the buffer in canonical format.
+<function>lwres_gnbaresponse_render()</function>
+performs the same task, except it converts a getnamebyaddr response structure
+<type>lwres_gnbaresponse_t</type>
+to the lightweight resolver's canonical format.
+</para>
+<para>
+<function>lwres_gnbarequest_parse()</function>
+uses context
+<varname>ctx</varname>
+to convert the contents of packet
+<varname>pkt</varname>
+to a
+<type>lwres_gnbarequest_t</type>
+structure.
+Buffer
+<varname>b</varname>
+provides space to be used for storing this structure.
+When the function succeeds, the resulting
+<type>lwres_gnbarequest_t</type>
+is made available through
+<varname>*structp</varname>.
+<function>lwres_gnbaresponse_parse()</function>
+offers the same semantics as
+<function>lwres_gnbarequest_parse()</function>
+except it yields a
+<type>lwres_gnbaresponse_t</type>
+structure.
+</para>
+<para>
+<function>lwres_gnbaresponse_free()</function>
+and
+<function>lwres_gnbarequest_free()</function>
+release the memory in resolver context
+<varname>ctx</varname>
+that was allocated to the
+<type>lwres_gnbaresponse_t</type>
+or
+<type>lwres_gnbarequest_t</type>
+structures referenced via
+<varname>structp</varname>.
+Any memory associated with ancillary buffers and strings for those
+structures is also discarded.
+</para>
+</refsect1>
+<refsect1>
+<title>RETURN VALUES</title>
+<para>
+The getnamebyaddr opcode functions
+<function>lwres_gnbarequest_render()</function>,
+<function>lwres_gnbaresponse_render()</function>
+<function>lwres_gnbarequest_parse()</function>
+and
+<function>lwres_gnbaresponse_parse()</function>
+all return
+<errorname>LWRES_R_SUCCESS</errorname>
+on success.
+They return
+<errorname>LWRES_R_NOMEMORY</errorname>
+if memory allocation fails.
+<errorname>LWRES_R_UNEXPECTEDEND</errorname>
+is returned if the available space in the buffer
+<varname>b</varname>
+is too small to accommodate the packet header or the
+<type>lwres_gnbarequest_t</type>
+and
+<type>lwres_gnbaresponse_t</type>
+structures.
+<function>lwres_gnbarequest_parse()</function>
+and
+<function>lwres_gnbaresponse_parse()</function>
+will return
+<errorname>LWRES_R_UNEXPECTEDEND</errorname>
+if the buffer is not empty after decoding the received packet.
+These functions will return
+<errorname>LWRES_R_FAILURE</errorname>
+if
+<structfield>pktflags</structfield>
+in the packet header structure
+<type>lwres_lwpacket_t</type>
+indicate that the packet is not a response to an earlier query.
+</para>
+</refsect1>
+<refsect1>
+<title>SEE ALSO</title>
+<para>
+        <citerefentry>
+          <refentrytitle>lwres_packet</refentrytitle>
+          <manvolnum>3</manvolnum>
+        </citerefentry>.
+</refsect1>
+</refentry>