lwres_buffer.html revision 4abdfc917e6635a7c81d1f931a0c79227e72d025
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews - Copyright (C) 2000, 2001 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
4abdfc917e6635a7c81d1f931a0c79227e72d025Mark Andrews<!-- $Id: lwres_buffer.html,v 1.20 2007/01/26 23:29:04 marka Exp $ -->
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
4abdfc917e6635a7c81d1f931a0c79227e72d025Mark Andrews<a name="id2476275"></a><div class="titlepage"></div>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<p>lwres_buffer_init, lwres_buffer_invalidate, lwres_buffer_add, lwres_buffer_subtract, lwres_buffer_clear, lwres_buffer_first, lwres_buffer_forward, lwres_buffer_back, lwres_buffer_getuint8, lwres_buffer_putuint8, lwres_buffer_getuint16, lwres_buffer_putuint16, lwres_buffer_getuint32, lwres_buffer_putuint32, lwres_buffer_putmem, lwres_buffer_getmem — lightweight resolver buffer management</p>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_init</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<var class="pdparam">length</var><code>)</code>;</td>
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_invalidate</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_add</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_subtract</b>(</code></td>
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_clear</b>(</code></td>
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_first</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_forward</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_back</b>(</code></td>
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_uint8_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_getuint8</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_putuint8</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<var class="pdparam">val</var><code>)</code>;</td>
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_uint16_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_getuint16</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_putuint16</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<var class="pdparam">val</var><code>)</code>;</td>
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_uint32_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_getuint32</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_putuint32</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<var class="pdparam">val</var><code>)</code>;</td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_putmem</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<var class="pdparam">length</var><code>)</code>;</td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_buffer_getmem</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<var class="pdparam">length</var><code>)</code>;</td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein These functions provide bounds checked access to a region of memory
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein where data is being read or written.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein They are based on, and similar to, the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein functions in the ISC library.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein A buffer is a region of memory, together with a set of related
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The <span class="emphasis"><em>used region</em></span> and the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="emphasis"><em>available</em></span> region are disjoint, and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein their union is the buffer's region.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The used region extends from the beginning of the buffer region to the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein last used byte.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The available region extends from one byte greater than the last used
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein byte to the end of the buffer's region.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The size of the used region can be changed using various
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein buffer commands.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Initially, the used region is empty.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The used region is further subdivided into two disjoint regions: the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="emphasis"><em>consumed region</em></span> and the <span class="emphasis"><em>remaining region</em></span>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The union of these two regions is the used region.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The consumed region extends from the beginning of the used region to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the byte before the <span class="emphasis"><em>current</em></span> offset (if any).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The <span class="emphasis"><em>remaining</em></span> region the current pointer to the end
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The size of the consumed region can be changed using various
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein buffer commands.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Initially, the consumed region is empty.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The <span class="emphasis"><em>active region</em></span> is an (optional) subregion of the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein It extends from the current offset to an offset in the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein remaining region.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Initially, the active region is empty.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If the current offset advances beyond the chosen offset,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the active region will also be empty.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson /------------entire length---------------\\
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson /----- used region -----\\/-- available --\\
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson +----------------------------------------+
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson | consumed | remaining | |
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson +----------------------------------------+
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson a == base of buffer.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson b == current pointer. Can be anywhere between a and d.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson c == active pointer. Meaningful between b and d.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson d == used pointer.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson e == length of buffer.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson a-e == entire length of buffer.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson a-d == used region.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson a-b == consumed region.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson b-d == remaining region.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein b-c == optional active region.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<p><code class="function">lwres_buffer_init()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein initializes the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein and assocates it with the memory region of size
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein bytes starting at location
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<p><code class="function">lwres_buffer_invalidate()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein marks the buffer <em class="parameter"><code>*b</code></em>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein as invalid. Invalidating a buffer after use is not required,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein but makes it possible to catch its possible accidental use.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The functions
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_add()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_subtract()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein respectively increase and decrease the used space in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_add()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein checks for buffer overflow and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_subtract()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein checks for underflow.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein These functions do not allocate or deallocate memory.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein They just change the value of
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein A buffer is re-initialised by
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_clear()</code>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The function sets
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="structfield"><code>current</code></em>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="structfield"><code>active</code></em>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<p><code class="function">lwres_buffer_first</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein makes the consumed region of buffer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein empty by setting
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="structfield"><code>current</code></em>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein to zero (the start of the buffer).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<p><code class="function">lwres_buffer_forward()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein increases the consumed region of buffer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein bytes, checking for overflow.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_back()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein decreases buffer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein consumed region by
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein bytes and checks for underflow.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<p><code class="function">lwres_buffer_getuint8()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein reads an unsigned 8-bit integer from
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein and returns it.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_putuint8()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein writes the unsigned 8-bit integer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<p><code class="function">lwres_buffer_getuint16()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_getuint32()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein are identical to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_putuint8()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein except that they respectively read an unsigned 16-bit or 32-bit integer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein in network byte order from
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_putuint16()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_putuint32()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein writes the unsigned 16-bit or 32-bit integer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein in network byte order.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Arbitrary amounts of data are read or written from a lightweight
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein resolver buffer with
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_getmem()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_putmem()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein respectively.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_putmem()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein bytes of memory at
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_buffer_getmem()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein bytes of memory from