diff options
Diffstat (limited to 'lib/liblwres/man/lwres_buffer.docbook')
| -rw-r--r-- | lib/liblwres/man/lwres_buffer.docbook | 378 |
1 files changed, 0 insertions, 378 deletions
diff --git a/lib/liblwres/man/lwres_buffer.docbook b/lib/liblwres/man/lwres_buffer.docbook deleted file mode 100644 index 8f9d55889..000000000 --- a/lib/liblwres/man/lwres_buffer.docbook +++ /dev/null @@ -1,378 +0,0 @@ -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -<!-- - - Copyright (C) 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 2004/03/15 20:35:25 as 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 <lwres/lwbuffer.h> -</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> |