lwres_buffer.docbook revision ec5347e2c775f027573ce5648b910361aa926c01
5cd4555ad444fd391002ae32450572054369fd42Rob Austein<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
5cd4555ad444fd391002ae32450572054369fd42Rob Austein "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein [<!ENTITY mdash "—">]>
c1a883f2e04d94e99c433b1f6cfd0c0338f4ed85Mark Andrews - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2000, 2001 Internet Software Consortium.
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater - Permission to use, copy, modify, and/or distribute this software for any
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater<!-- $Id: lwres_buffer.docbook,v 1.10 2007/06/18 23:47:51 tbox Exp $ -->
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refpurpose>lightweight resolver buffer management</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcsynopsisinfo>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcsynopsisinfo>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_init</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>void *<parameter>base</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>length</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_invalidate</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_add</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>n</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_subtract</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>n</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_clear</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_first</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_forward</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>n</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_back</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>n</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint8</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint8</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint8_t <parameter>val</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint16</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint16</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint16_t <parameter>val</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint32</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint32</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint32_t <parameter>val</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putmem</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>const unsigned char *<parameter>base</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>length</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getmem</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned char *<parameter>base</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>length</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These functions provide bounds checked access to a region of memory
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein where data is being read or written.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein They are based on, and similar to, the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein functions in the ISC library.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein A buffer is a region of memory, together with a set of related
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <emphasis>available</emphasis> region are disjoint, and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein their union is the buffer's region.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The used region extends from the beginning of the buffer region to the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein last used byte.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The available region extends from one byte greater than the last used
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein byte to the end of the buffer's region.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The size of the used region can be changed using various
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein buffer commands.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Initially, the used region is empty.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The used region is further subdivided into two disjoint regions: the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The union of these two regions is the used region.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The consumed region extends from the beginning of the used region to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the byte before the <emphasis>current</emphasis> offset (if any).
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The <emphasis>remaining</emphasis> region the current pointer to the end
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The size of the consumed region can be changed using various
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein buffer commands.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Initially, the consumed region is empty.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The <emphasis>active region</emphasis> is an (optional) subregion of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein It extends from the current offset to an offset in the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein remaining region.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Initially, the active region is empty.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If the current offset advances beyond the chosen offset,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the active region will also be empty.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson /------------entire length---------------\\
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson /----- used region -----\\/-- available --\\
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson +----------------------------------------+
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson | consumed | remaining | |
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson +----------------------------------------+
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </programlisting>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson a == base of buffer.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson b == current pointer. Can be anywhere between a and d.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson c == active pointer. Meaningful between b and d.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson d == used pointer.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson e == length of buffer.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </programlisting>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson a-e == entire length of buffer.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson a-d == used region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson a-b == consumed region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson b-d == remaining region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson b-c == optional active region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</programlisting>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein initializes the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and assocates it with the memory region of size
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bytes starting at location
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_buffer_invalidate()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein as invalid. Invalidating a buffer after use is not required,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein but makes it possible to catch its possible accidental use.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The functions
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein respectively increase and decrease the used space in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein checks for buffer overflow and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein checks for underflow.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These functions do not allocate or deallocate memory.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein They just change the value of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein A buffer is re-initialised by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The function sets
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein makes the consumed region of buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein empty by setting
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to zero (the start of the buffer).
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_buffer_forward()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein increases the consumed region of buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bytes, checking for overflow.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein decreases buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein consumed region by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bytes and checks for underflow.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_buffer_getuint8()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein reads an unsigned 8-bit integer from
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and returns it.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein writes the unsigned 8-bit integer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_buffer_getuint16()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein are identical to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein except that they respectively read an unsigned 16-bit or 32-bit integer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in network byte order from
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein writes the unsigned 16-bit or 32-bit integer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in network byte order.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Arbitrary amounts of data are read or written from a lightweight
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein resolver buffer with
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein respectively.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bytes of memory at
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bytes of memory from
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - Local variables:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - mode: sgml