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