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