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