2N/A<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"

2N/A "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"

2N/A [<!ENTITY mdash "&#8212;">]>

2N/A

2N/A<refentry>

2N/A <refentryinfo>

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

2N/A </refentryinfo>

2N/A

2N/A <refmeta>

2N/A <refentrytitle>lwres_buffer</refentrytitle>

2N/A <manvolnum>3</manvolnum>

2N/A <refmiscinfo>BIND9</refmiscinfo>

2N/A </refmeta>

2N/A

2N/A <docinfo>

2N/A <copyright>

2N/A <year>2004</year>

2N/A <year>2005</year>

2N/A <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

2N/A </copyright>

2N/A <copyright>

2N/A <year>2000</year>

2N/A <year>2001</year>

2N/A <holder>Internet Software Consortium.</holder>

2N/A </copyright>

2N/A </docinfo>

2N/A

2N/A <refnamediv>

2N/A <refname>lwres_buffer_init</refname>

2N/A <refname>lwres_buffer_invalidate</refname>

2N/A <refname>lwres_buffer_add</refname>

2N/A <refname>lwres_buffer_subtract</refname>

2N/A <refname>lwres_buffer_clear</refname>

2N/A <refname>lwres_buffer_first</refname>

2N/A <refname>lwres_buffer_forward</refname>

2N/A <refname>lwres_buffer_back</refname>

2N/A <refname>lwres_buffer_getuint8</refname>

2N/A <refname>lwres_buffer_putuint8</refname>

2N/A <refname>lwres_buffer_getuint16</refname>

2N/A <refname>lwres_buffer_putuint16</refname>

2N/A <refname>lwres_buffer_getuint32</refname>

2N/A <refname>lwres_buffer_putuint32</refname>

2N/A <refname>lwres_buffer_putmem</refname>

2N/A <refname>lwres_buffer_getmem</refname>

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

2N/A </refnamediv>

2N/A

2N/A <refsynopsisdiv>

2N/A

2N/A <funcsynopsis>

2N/A<funcsynopsisinfo>

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

2N/A</funcsynopsisinfo>

2N/A

2N/A<funcprototype>

2N/A

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A <paramdef>void *<parameter>base</parameter></paramdef>

2N/A <paramdef>unsigned int <parameter>length</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A </funcprototype>

2N/A<funcprototype>

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A <paramdef>unsigned int <parameter>n</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A <paramdef>unsigned int <parameter>n</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A <paramdef>unsigned int <parameter>n</parameter></paramdef>

2N/A </funcprototype>

2N/A<funcprototype>

2N/A

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A <paramdef>unsigned int <parameter>n</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Alwres_uint8_t

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A <paramdef>lwres_uint8_t <parameter>val</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Alwres_uint16_t

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A <paramdef>lwres_uint16_t <parameter>val</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Alwres_uint32_t

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A <paramdef>lwres_uint32_t <parameter>val</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A <paramdef>const unsigned char *<parameter>base</parameter></paramdef>

2N/A <paramdef>unsigned int <parameter>length</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A<funcprototype>

2N/A <funcdef>

2N/Avoid

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

2N/A <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

2N/A <paramdef>unsigned char *<parameter>base</parameter></paramdef>

2N/A <paramdef>unsigned int <parameter>length</parameter></paramdef>

2N/A </funcprototype>

2N/A

2N/A</funcsynopsis>

2N/A </refsynopsisdiv>

2N/A

2N/A <refsect1>

2N/A

2N/A <title>DESCRIPTION</title>

2N/A <para>

2N/A These functions provide bounds checked access to a region of memory

2N/A where data is being read or written.

2N/A They are based on, and similar to, the

2N/A <literal>isc_buffer_</literal>

2N/A functions in the ISC library.

2N/A </para>

2N/A <para>

2N/A A buffer is a region of memory, together with a set of related

2N/A subregions.

2N/A The <emphasis>used region</emphasis> and the

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

2N/A their union is the buffer's region.

2N/A The used region extends from the beginning of the buffer region to the

2N/A last used byte.

2N/A The available region extends from one byte greater than the last used

2N/A byte to the end of the buffer's region.

2N/A The size of the used region can be changed using various

2N/A buffer commands.

2N/A Initially, the used region is empty.

2N/A </para>

2N/A <para>

2N/A The used region is further subdivided into two disjoint regions: the

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

2N/A The union of these two regions is the used region.

2N/A The consumed region extends from the beginning of the used region to

2N/A the byte before the <emphasis>current</emphasis> offset (if any).

2N/A The <emphasis>remaining</emphasis> region the current pointer to the end

2N/A of the used

2N/A region.

2N/A The size of the consumed region can be changed using various

2N/A buffer commands.

2N/A Initially, the consumed region is empty.

2N/A </para>

2N/A <para>

2N/A The <emphasis>active region</emphasis> is an (optional) subregion of the

2N/A remaining

2N/A region.

2N/A It extends from the current offset to an offset in the

2N/A remaining region.

2N/A Initially, the active region is empty.

2N/A If the current offset advances beyond the chosen offset,

2N/A the active region will also be empty.

2N/A </para>

2N/A <para><programlisting>

2N/A /------------entire length---------------\\

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

2N/A +----------------------------------------+

2N/A | consumed | remaining | |

2N/A +----------------------------------------+

2N/A a b c d e

2N/A </programlisting>

2N/A </para>

2N/A <para><programlisting>

2N/A a == base of buffer.

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

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

2N/A d == used pointer.

2N/A e == length of buffer.

2N/A </programlisting>

2N/A </para>

2N/A <para><programlisting>

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

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

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

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

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

2N/A</programlisting>

2N/A </para>

2N/A <para><function>lwres_buffer_init()</function>

2N/A initializes the

2N/A <type>lwres_buffer_t</type>

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

2N/A and assocates it with the memory region of size

2N/A <parameter>length</parameter>

2N/A bytes starting at location

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

2N/A </para>

2N/A <para><function>lwres_buffer_invalidate()</function>

2N/A marks the buffer <parameter>*b</parameter>

2N/A as invalid. Invalidating a buffer after use is not required,

2N/A but makes it possible to catch its possible accidental use.

2N/A </para>

2N/A <para>

2N/A The functions

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

2N/A and

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

2N/A respectively increase and decrease the used space in

2N/A buffer

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

2N/A by

2N/A <parameter>n</parameter>

2N/A bytes.

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

2N/A checks for buffer overflow and

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

2N/A checks for underflow.

2N/A These functions do not allocate or deallocate memory.

2N/A They just change the value of

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

2N/A </para>

2N/A <para>

2N/A A buffer is re-initialised by

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

2N/A The function sets

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

2N/A <structfield>current</structfield>

2N/A and

2N/A <structfield>active</structfield>

2N/A to zero.

2N/A </para>

2N/A <para><function>lwres_buffer_first</function>

2N/A makes the consumed region of buffer

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

2N/A empty by setting

2N/A <structfield>current</structfield>

2N/A to zero (the start of the buffer).

2N/A </para>

2N/A <para><function>lwres_buffer_forward()</function>

2N/A increases the consumed region of buffer

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

2N/A by

2N/A <parameter>n</parameter>

2N/A bytes, checking for overflow.

2N/A Similarly,

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

2N/A decreases buffer

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

2N/A consumed region by

2N/A <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><!--