493N/A<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

493N/A

1466N/A

1466N/A<refentry>

1466N/A <refentryinfo>

1466N/A<date>Jun 30, 2000</date>

1466N/A</refentryinfo>

493N/A

493N/A<refmeta>

1466N/A <refentrytitle>lwres_buffer</refentrytitle>

1466N/A <manvolnum>3</manvolnum>

1466N/A <refmiscinfo>BIND9</refmiscinfo>

1466N/A</refmeta>

1466N/A

1466N/A<refnamediv>

970N/A<refname>lwres_buffer_init</refname>

1466N/A<refname>lwres_buffer_invalidate</refname>

970N/A<refname>lwres_buffer_add</refname>

970N/A<refname>lwres_buffer_subtract</refname>

970N/A<refname>lwres_buffer_clear</refname>

493N/A<refname>lwres_buffer_first</refname>

493N/A<refname>lwres_buffer_forward</refname>

1466N/A<refname>lwres_buffer_back</refname>

493N/A<refname>lwres_buffer_getuint8</refname>

493N/A<refname>lwres_buffer_putuint8</refname>

493N/A<refname>lwres_buffer_getuint16</refname>

493N/A<refname>lwres_buffer_putuint16</refname>

493N/A<refname>lwres_buffer_getuint32</refname>

493N/A<refname>lwres_buffer_putuint32</refname>

493N/A<refname>lwres_buffer_putmem</refname>

493N/A<refname>lwres_buffer_getmem</refname>

493N/A<refpurpose>lightweight resolver buffer management</refpurpose>

493N/A</refnamediv>

493N/A

1466N/A<refsynopsisdiv>

493N/A

493N/A<funcsynopsis>

493N/A<funcsynopsisinfo>

493N/A#include &lt;lwres/lwbuffer.h&gt;

1466N/A</funcsynopsisinfo>

1466N/A

1466N/A<funcprototype>

1466N/A

493N/A<funcdef>

493N/Avoid

1466N/A<function>lwres_buffer_init</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A<paramdef>void *base</paramdef>

493N/A<paramdef>unsigned int length</paramdef>

493N/A</funcprototype>

493N/A

1466N/A<funcprototype>

1466N/A<funcdef>

493N/Avoid

493N/A<function>lwres_buffer_invalidate</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A</funcprototype>

493N/A<funcprototype>

493N/A<funcdef>

493N/Avoid

493N/A<function>lwres_buffer_add</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A<paramdef>unsigned int n</paramdef>

493N/A</funcprototype>

493N/A

493N/A<funcprototype>

493N/A<funcdef>

1466N/Avoid

1466N/A<function>lwres_buffer_subtract</function></funcdef>

1466N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A<paramdef>unsigned int n</paramdef>

493N/A</funcprototype>

493N/A

1466N/A<funcprototype>

493N/A<funcdef>

493N/Avoid

493N/A<function>lwres_buffer_clear</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A</funcprototype>

493N/A

493N/A<funcprototype>

493N/A<funcdef>

493N/Avoid

493N/A<function>lwres_buffer_first</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A</funcprototype>

493N/A

493N/A<funcprototype>

970N/A<funcdef>

970N/Avoid

970N/A<function>lwres_buffer_forward</function></funcdef>

1466N/A<paramdef>lwres_buffer_t *b</paramdef>

970N/A<paramdef>unsigned int n</paramdef>

970N/A</funcprototype>

970N/A<funcprototype>

970N/A

493N/A<funcdef>

493N/Avoid

493N/A<function>lwres_buffer_back</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A<paramdef>unsigned int n</paramdef>

493N/A</funcprototype>

493N/A

493N/A<funcprototype>

493N/A<funcdef>

493N/Alwres_uint8_t

493N/A<function>lwres_buffer_getuint8</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A</funcprototype>

493N/A

493N/A<funcprototype>

493N/A<funcdef>

493N/Avoid

1466N/A<function>lwres_buffer_putuint8</function></funcdef>

1466N/A<paramdef>lwres_buffer_t *b</paramdef>

1466N/A<paramdef>lwres_uint8_t val</paramdef>

493N/A</funcprototype>

1466N/A

493N/A<funcprototype>

533N/A<funcdef>

493N/Alwres_uint16_t

493N/A<function>lwres_buffer_getuint16</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A</funcprototype>

493N/A

493N/A<funcprototype>

493N/A<funcdef>

493N/Avoid

493N/A<function>lwres_buffer_putuint16</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A<paramdef>lwres_uint16_t val</paramdef>

493N/A</funcprototype>

493N/A

493N/A<funcprototype>

493N/A<funcdef>

493N/Alwres_uint32_t

493N/A<function>lwres_buffer_getuint32</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A</funcprototype>

493N/A

493N/A<funcprototype>

493N/A<funcdef>

493N/Avoid

493N/A<function>lwres_buffer_putuint32</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A<paramdef>lwres_uint32_t val</paramdef>

493N/A</funcprototype>

493N/A

493N/A<funcprototype>

493N/A<funcdef>

1466N/Avoid

970N/A<function>lwres_buffer_putmem</function></funcdef>

1466N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A<paramdef>const unsigned char *base</paramdef>

1466N/A<paramdef>unsigned int length</paramdef>

493N/A</funcprototype>

493N/A

493N/A<funcprototype>

493N/A<funcdef>

493N/Avoid

493N/A<function>lwres_buffer_getmem</function></funcdef>

493N/A<paramdef>lwres_buffer_t *b</paramdef>

493N/A<paramdef>unsigned char *base</paramdef>

493N/A<paramdef>unsigned int length</paramdef>

493N/A</funcprototype>

493N/A

493N/A</funcsynopsis>

493N/A</refsynopsisdiv>

493N/A

493N/A<refsect1>

493N/A

493N/A<title>DESCRIPTION</title>

493N/A<para>

493N/AThese functions provide bounds checked access to a region of memory

493N/Awhere data is being read or written.

493N/AThey are based on, and similar to, the

493N/A<literal>isc_buffer_</literal>

493N/Afunctions in the ISC library.

1466N/A</para>

493N/A<para>

493N/AA buffer is a region of memory, together with a set of related

493N/Asubregions.

1466N/AThe <emphasis>used region</emphasis> and the

1466N/A<emphasis>available</emphasis> region are disjoint, and

1466N/Atheir union is the buffer's region.

1466N/AThe used region extends from the beginning of the buffer region to the

1466N/Alast used byte.

493N/AThe available region extends from one byte greater than the last used

493N/Abyte to the end of the buffer's region.

493N/AThe size of the used region can be changed using various

493N/Abuffer commands.

493N/AInitially, the used region is empty.

493N/A</para>

493N/A<para>

493N/AThe used region is further subdivided into two disjoint regions: the

851N/A<emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.

851N/AThe union of these two regions is the used region.

493N/AThe consumed region extends from the beginning of the used region to

493N/Athe byte before the <emphasis>current</emphasis> offset (if any).

493N/AThe <emphasis>remaining</emphasis> region the current pointer to the end of the used

493N/Aregion.

970N/AThe size of the consumed region can be changed using various

970N/Abuffer commands.

970N/AInitially, the consumed region is empty.

970N/A</para>

970N/A<para>

1356N/AThe <emphasis>active region</emphasis> is an (optional) subregion of the remaining

1356N/Aregion.

1466N/AIt extends from the current offset to an offset in the

1466N/Aremaining region.

1466N/AInitially, the active region is empty.

1466N/AIf the current offset advances beyond the chosen offset,

1356N/Athe active region will also be empty.

1356N/A</para>

1356N/A<para>

1356N/A<programlisting>

1356N/A

1356N/A /------------entire length---------------\\

1356N/A /----- used region -----\\/-- available --\\

1003N/A +----------------------------------------+

1003N/A | consumed | remaining | |

1003N/A +----------------------------------------+

1003N/A a b c d e

1356N/A

1356N/A a == base of buffer.

1356N/A b == current pointer. Can be anywhere between a and d.

1356N/A c == active pointer. Meaningful between b and d.

1356N/A d == used pointer.

1356N/A e == length of buffer.

1356N/A

1356N/A a-e == entire length of buffer.

1356N/A a-d == used region.

493N/A a-b == consumed region.

493N/A b-d == remaining region.

493N/A b-c == optional active region.

493N/A</programlisting>

493N/A</para>

1466N/A<para>

493N/A<function>lwres_buffer_init()</function>

493N/Ainitializes the

493N/A<type>lwres_buffer_t</type>

1466N/A<parameter>*b</parameter>

591N/Aand assocates it with the memory region of size

591N/A<parameter>length</parameter>

1466N/Abytes starting at location

1466N/A<parameter>base.</parameter>

591N/A</para>

493N/A<para>

493N/A<function>lwres_buffer_invalidate()</function>

493N/Amarks the buffer

493N/A<parameter>*b</parameter>

1466N/Aas invalid. Invalidating a buffer after use is not required,

493N/Abut makes it possible to catch its possible accidental use.

493N/A</para>

493N/A<para>

493N/AThe functions

493N/A<function>lwres_buffer_add()</function>

493N/Aand

493N/A<function>lwres_buffer_subtract()</function>

493N/Arespectively increase and decrease the used space in

493N/Abuffer

493N/A<parameter>*b</parameter>

493N/Aby

1466N/A<parameter>n</parameter>

493N/Abytes.

493N/A<function>lwres_buffer_add()</function>

606N/Achecks for buffer overflow and

606N/A<function>lwres_buffer_subtract()</function>

606N/Achecks for underflow.

606N/AThese functions do not allocate or deallocate memory.

493N/AThey just change the value of

493N/A<structfield>used</structfield>.

493N/A</para>

493N/A<para>

493N/AA buffer is re-initialised by

493N/A<function>lwres_buffer_clear()</function>.

493N/AThe function sets

493N/A<structfield>used</structfield> ,

493N/A<structfield>current</structfield>

493N/Aand

493N/A<structfield>active</structfield>

493N/Ato zero.

493N/A</para>

493N/A<para>

493N/A<function>lwres_buffer_first</function>

493N/Amakes the consumed region of buffer

493N/A<parameter>*p</parameter>

493N/Aempty by setting

493N/A<structfield>current</structfield>

493N/Ato zero (the start of the buffer).

1466N/A</para>

1466N/A<para>

1466N/A<function>lwres_buffer_forward()</function>

493N/Aincreases the consumed region of buffer

493N/A<parameter>*b</parameter>

493N/Aby

493N/A<parameter>n</parameter>

493N/Abytes, checking for overflow.

493N/ASimilarly,

493N/A<function>lwres_buffer_back()</function>

493N/Adecreases buffer

493N/A<parameter>b</parameter>'s

493N/Aconsumed region by

493N/A<parameter>n</parameter>

493N/Abytes and checks for underflow.

493N/A</para>

493N/A<para>

493N/A<function>lwres_buffer_getuint8()</function>

493N/Areads an unsigned 8-bit integer from

493N/A<parameter>*b</parameter>

493N/Aand returns it.

493N/A<function>lwres_buffer_putuint8()</function>

493N/Awrites the unsigned 8-bit integer

493N/A<parameter>val</parameter>

493N/Ato buffer

493N/A<parameter>*b</parameter>.

493N/A</para>

493N/A<para>

493N/A<function>lwres_buffer_getuint16()</function>

493N/Aand

970N/A<function>lwres_buffer_getuint32()</function>

970N/Aare identical to

970N/A<function>lwres_buffer_putuint8()</function>

970N/Aexcept that they respectively read an unsigned 16-bit or 32-bit integer

1466N/Ain network byte order from

970N/A<parameter>b</parameter>.

970N/ASimilarly,

587N/A<function>lwres_buffer_putuint16()</function>

493N/Aand

493N/A<function>lwres_buffer_putuint32()</function>

493N/Awrites the unsigned 16-bit or 32-bit integer

493N/A<parameter>val</parameter>

493N/Ato buffer

493N/A<parameter>b</parameter>,

493N/Ain network byte order.

493N/A</para>

493N/A<para>

970N/AArbitrary amounts of data are read or written from a lightweight

1466N/Aresolver buffer with

970N/A<function>lwres_buffer_getmem()</function>

970N/Aand

970N/A<function>lwres_buffer_putmem()</function>

970N/Arespectively.

970N/A<function>lwres_buffer_putmem()</function>

970N/Acopies

970N/A<parameter>length</parameter>

970N/Abytes of memory at

970N/A<parameter>base</parameter>

970N/Ato

970N/A<parameter>b</parameter>.

970N/AConversely,

970N/A<function>lwres_buffer_getmem()</function>

970N/Acopies

970N/A<parameter>length</parameter>

970N/Abytes of memory from

970N/A<parameter>b</parameter>

970N/Ato

970N/A<parameter>base</parameter>.

970N/A</para>

970N/A</refsect1>

970N/A</refentry>

493N/A