lwres_buffer.docbook revision ddccd5811feff696ba460dabfb666ce61040f545
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - Copyright (C) 2000, 2001 Internet Software Consortium.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - Permission to use, copy, modify, and 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.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!-- $Id: lwres_buffer.docbook,v 1.2 2001/03/31 00:08:02 gson Exp $ -->
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</refentryinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_buffer</refentrytitle>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<refname>lwres_buffer_invalidate</refname>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<refpurpose>lightweight resolver buffer management</refpurpose>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<refsynopsisdiv>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcsynopsisinfo>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcsynopsisinfo>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_init</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_invalidate</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_add</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_subtract</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_clear</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_first</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_forward</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_back</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint8</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint8</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint16</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint16</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint32</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint32</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putmem</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>const unsigned char *base</paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getmem</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcsynopsis>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</refsynopsisdiv>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThese functions provide bounds checked access to a region of memory
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonwhere data is being read or written.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThey are based on, and similar to, the
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonfunctions in the ISC library.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonA buffer is a region of memory, together with a set of related
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe <emphasis>used region</emphasis> and the
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<emphasis>available</emphasis> region are disjoint, and
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssontheir union is the buffer's region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe used region extends from the beginning of the buffer region to the
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonlast used byte.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe available region extends from one byte greater than the last used
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonbyte to the end of the buffer's region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe size of the used region can be changed using various
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonbuffer commands.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonInitially, the used region is empty.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe used region is further subdivided into two disjoint regions: the
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe union of these two regions is the used region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe consumed region extends from the beginning of the used region to
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonthe byte before the <emphasis>current</emphasis> offset (if any).
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe <emphasis>remaining</emphasis> region the current pointer to the end of the used
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe size of the consumed region can be changed using various
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonbuffer commands.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonInitially, the consumed region is empty.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe <emphasis>active region</emphasis> is an (optional) subregion of the remaining
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonIt extends from the current offset to an offset in the
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonremaining region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonInitially, the active region is empty.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonIf the current offset advances beyond the chosen offset,
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonthe active region will also be empty.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<programlisting>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson /------------entire length---------------\\
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson /----- used region -----\\/-- available --\\
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson +----------------------------------------+
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson | consumed | remaining | |
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson +----------------------------------------+
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.
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>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssoninitializes the
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonand assocates it with the memory region of size
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonbytes starting at location
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_invalidate()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonmarks the buffer
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonas invalid. Invalidating a buffer after use is not required,
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonbut makes it possible to catch its possible accidental use.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_subtract()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonrespectively increase and decrease the used space in
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonchecks for buffer overflow and
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_subtract()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonchecks for underflow.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThese functions do not allocate or deallocate memory.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThey just change the value of
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonA buffer is re-initialised by
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_clear()</function>.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe function sets
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonmakes the consumed region of buffer
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonempty by setting
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonto zero (the start of the buffer).
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_forward()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonincreases the consumed region of buffer
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonbytes, checking for overflow.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssondecreases buffer
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonconsumed region by
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonbytes and checks for underflow.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint8()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonreads an unsigned 8-bit integer from
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonand returns it.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint8()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonwrites the unsigned 8-bit integer
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint16()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint32()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonare identical to
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint8()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonexcept that they respectively read an unsigned 16-bit or 32-bit integer
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonin network byte order from
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint16()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint32()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonwrites the unsigned 16-bit or 32-bit integer
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonin network byte order.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonArbitrary amounts of data are read or written from a lightweight
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonresolver buffer with
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getmem()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putmem()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putmem()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonbytes of memory at
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getmem()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonbytes of memory from