2N/A - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC") 2N/A - This Source Code Form is subject to the terms of the Mozilla Public 2N/A - License, v. 2.0. If a copy of the MPL was not distributed with this 2N/A<
meta http-
equiv="Content-Type" content="text/html; charset=ISO-8859-1">
2N/A<
title>lwres_buffer</
title>
2N/A<
meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
2N/A<
body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><
div class="refentry">
2N/A<
a name="id-1"></
a><
div class="titlepage"></
div>
2N/A<
div class="refnamediv">
2N/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>
2N/A<
div class="refsynopsisdiv">
2N/A<
div class="funcsynopsis">
2N/A<
pre class="funcsynopsisinfo">
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_init</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var>, </
td>
2N/A<
td>void *<
var class="pdparam">base</
var>, </
td>
2N/A<
td>unsigned int <
var class="pdparam">length</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><
tr>
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_invalidate</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_add</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var>, </
td>
2N/A<
td>unsigned int <
var class="pdparam">n</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_subtract</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var>, </
td>
2N/A<
td>unsigned int <
var class="pdparam">n</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><
tr>
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_clear</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><
tr>
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_first</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_forward</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var>, </
td>
2N/A<
td>unsigned int <
var class="pdparam">n</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_back</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var>, </
td>
2N/A<
td>unsigned int <
var class="pdparam">n</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><
tr>
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_getuint8</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_putuint8</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var>, </
td>
2N/A<
td>lwres_uint8_t <
var class="pdparam">val</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><
tr>
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_getuint16</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_putuint16</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var>, </
td>
2N/A<
td>lwres_uint16_t <
var class="pdparam">val</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><
tr>
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_getuint32</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_putuint32</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var>, </
td>
2N/A<
td>lwres_uint32_t <
var class="pdparam">val</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_putmem</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var>, </
td>
2N/A<
td>const unsigned char *<
var class="pdparam">base</
var>, </
td>
2N/A<
td>unsigned int <
var class="pdparam">length</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
2N/A<
td><
code class="funcdef">
2N/A<
b class="fsfunc">lwres_buffer_getmem</
b>(</
code></
td>
2N/A<
td>lwres_buffer_t *<
var class="pdparam">b</
var>, </
td>
2N/A<
td>unsigned char *<
var class="pdparam">base</
var>, </
td>
2N/A<
td>unsigned int <
var class="pdparam">length</
var><
code>)</
code>;</
td>
2N/A<
div class="funcprototype-spacer">�</
div>
2N/A<
div class="refsection">
2N/A<
a name="id-1.7"></
a><
h2>DESCRIPTION</
h2>
2N/A These functions provide bounds checked access to a region of memory
2N/A where data is being read or written.
2N/A They are based on, and similar to, the
2N/A <
code class="literal">isc_buffer_</
code>
2N/A functions in the ISC library.
2N/A A buffer is a region of memory, together with a set of related
2N/A The <
span class="emphasis"><
em>used region</
em></
span> and the
2N/A <
span class="emphasis"><
em>available</
em></
span> region are disjoint, and
2N/A their union is the buffer's region.
2N/A The used region extends from the beginning of the buffer region to the
2N/A The available region extends from one byte greater than the last used
2N/A byte to the end of the buffer's region.
2N/A The size of the used region can be changed using various
2N/A Initially, the used region is empty.
2N/A The used region is further subdivided into two disjoint regions: the
2N/A <
span class="emphasis"><
em>consumed region</
em></
span> and the <
span class="emphasis"><
em>remaining region</
em></
span>.
2N/A The union of these two regions is the used region.
2N/A The consumed region extends from the beginning of the used region to
2N/A the byte before the <
span class="emphasis"><
em>current</
em></
span> offset (if any).
2N/A The <
span class="emphasis"><
em>remaining</
em></
span> region the current pointer to the end
2N/A The size of the consumed region can be changed using various
2N/A Initially, the consumed region is empty.
2N/A The <
span class="emphasis"><
em>active region</
em></
span> is an (optional) subregion of the
2N/A It extends from the current offset to an offset in the
2N/A Initially, the active region is empty.
2N/A If the current offset advances beyond the chosen offset,
2N/A the active region will also be empty.
2N/A<
pre class="programlisting">
2N/A /------------entire length---------------\\
2N/A /----- used region -----\\/-- available --\\
2N/A +----------------------------------------+
2N/A | consumed | remaining | |
2N/A +----------------------------------------+
2N/A<
pre class="programlisting">
2N/A a == base of buffer.
2N/A b == current pointer. Can be anywhere between a and d.
2N/A c == active pointer. Meaningful between b and d.
2N/A e == length of buffer.
2N/A<
pre class="programlisting">
2N/A a-e == entire length of buffer.
2N/A a-b == consumed region.
2N/A b-d == remaining region.
2N/A b-c == optional active region.
2N/A<
p><
code class="function">lwres_buffer_init()</
code>
2N/A <
span class="type">lwres_buffer_t</
span>
2N/A <
em class="parameter"><
code>*b</
code></
em>
2N/A and assocates it with the memory region of size
2N/A <
em class="parameter"><
code>length</
code></
em>
2N/A bytes starting at location
2N/A <
em class="parameter"><
code>base.</
code></
em>
2N/A<
p><
code class="function">lwres_buffer_invalidate()</
code>
2N/A marks the buffer <
em class="parameter"><
code>*b</
code></
em>
2N/A as invalid. Invalidating a buffer after use is not required,
2N/A but makes it possible to catch its possible accidental use.
<
code class="function">lwres_buffer_add()</
code>
<
code class="function">lwres_buffer_subtract()</
code>
respectively increase and decrease the used space in
<
em class="parameter"><
code>*b</
code></
em>
<
em class="parameter"><
code>n</
code></
em>
<
code class="function">lwres_buffer_add()</
code>
checks for buffer overflow and
<
code class="function">lwres_buffer_subtract()</
code>
These functions do not allocate or deallocate memory.
They just change the value of
<
code class="varname">used</
code>.
A buffer is re-initialised by
<
code class="function">lwres_buffer_clear()</
code>.
<
code class="varname">used</
code>,
<
code class="varname">current</
code>
<
code class="varname">active</
code>
<
p><
code class="function">lwres_buffer_first</
code>
makes the consumed region of buffer
<
em class="parameter"><
code>*p</
code></
em>
<
code class="varname">current</
code>
to zero (the start of the buffer).
<
p><
code class="function">lwres_buffer_forward()</
code>
increases the consumed region of buffer
<
em class="parameter"><
code>*b</
code></
em>
<
em class="parameter"><
code>n</
code></
em>
bytes, checking for overflow.
<
code class="function">lwres_buffer_back()</
code>
<
em class="parameter"><
code>b</
code></
em>'s
<
em class="parameter"><
code>n</
code></
em>
bytes and checks for underflow.
<
p><
code class="function">lwres_buffer_getuint8()</
code>
reads an unsigned 8-bit integer from
<
em class="parameter"><
code>*b</
code></
em>
<
code class="function">lwres_buffer_putuint8()</
code>
writes the unsigned 8-bit integer
<
em class="parameter"><
code>val</
code></
em>
<
em class="parameter"><
code>*b</
code></
em>.
<
p><
code class="function">lwres_buffer_getuint16()</
code>
<
code class="function">lwres_buffer_getuint32()</
code>
<
code class="function">lwres_buffer_putuint8()</
code>
except that they respectively read an unsigned 16-bit or 32-bit integer
in network byte order from
<
em class="parameter"><
code>b</
code></
em>.
<
code class="function">lwres_buffer_putuint16()</
code>
<
code class="function">lwres_buffer_putuint32()</
code>
writes the unsigned 16-bit or 32-bit integer
<
em class="parameter"><
code>val</
code></
em>
<
em class="parameter"><
code>b</
code></
em>,
Arbitrary amounts of data are read or written from a lightweight
<
code class="function">lwres_buffer_getmem()</
code>
<
code class="function">lwres_buffer_putmem()</
code>
<
code class="function">lwres_buffer_putmem()</
code>
<
em class="parameter"><
code>length</
code></
em>
<
em class="parameter"><
code>base</
code></
em>
<
em class="parameter"><
code>b</
code></
em>.
<
code class="function">lwres_buffer_getmem()</
code>
<
em class="parameter"><
code>length</
code></
em>
<
em class="parameter"><
code>b</
code></
em>
<
em class="parameter"><
code>base</
code></
em>.