1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
3 - Copyright (C) 2001 Internet Software Consortium.
5 - Permission to use, copy, modify, and distribute this software for any
6 - purpose with or without fee is hereby granted, provided that the above
7 - copyright notice and this permission notice appear in all copies.
9 - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
10 - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
11 - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
12 - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
13 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
14 - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
15 - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
16 - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
19 <!-- $Id: lwres_buffer.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
23 <date>Jun 30, 2000</date>
27 <refentrytitle>lwres_buffer</refentrytitle>
28 <manvolnum>3</manvolnum>
29 <refmiscinfo>BIND9</refmiscinfo>
33 <refname>lwres_buffer_init</refname>
34 <refname>lwres_buffer_invalidate</refname>
35 <refname>lwres_buffer_add</refname>
36 <refname>lwres_buffer_subtract</refname>
37 <refname>lwres_buffer_clear</refname>
38 <refname>lwres_buffer_first</refname>
39 <refname>lwres_buffer_forward</refname>
40 <refname>lwres_buffer_back</refname>
41 <refname>lwres_buffer_getuint8</refname>
42 <refname>lwres_buffer_putuint8</refname>
43 <refname>lwres_buffer_getuint16</refname>
44 <refname>lwres_buffer_putuint16</refname>
45 <refname>lwres_buffer_getuint32</refname>
46 <refname>lwres_buffer_putuint32</refname>
47 <refname>lwres_buffer_putmem</refname>
48 <refname>lwres_buffer_getmem</refname>
49 <refpurpose>lightweight resolver buffer management</refpurpose>
56 #include <lwres/lwbuffer.h>
63 <function>lwres_buffer_init</function></funcdef>
64 <paramdef>lwres_buffer_t *b</paramdef>
65 <paramdef>void *base</paramdef>
66 <paramdef>unsigned int length</paramdef>
72 <function>lwres_buffer_invalidate</function></funcdef>
73 <paramdef>lwres_buffer_t *b</paramdef>
78 <function>lwres_buffer_add</function></funcdef>
79 <paramdef>lwres_buffer_t *b</paramdef>
80 <paramdef>unsigned int n</paramdef>
86 <function>lwres_buffer_subtract</function></funcdef>
87 <paramdef>lwres_buffer_t *b</paramdef>
88 <paramdef>unsigned int n</paramdef>
94 <function>lwres_buffer_clear</function></funcdef>
95 <paramdef>lwres_buffer_t *b</paramdef>
101 <function>lwres_buffer_first</function></funcdef>
102 <paramdef>lwres_buffer_t *b</paramdef>
108 <function>lwres_buffer_forward</function></funcdef>
109 <paramdef>lwres_buffer_t *b</paramdef>
110 <paramdef>unsigned int n</paramdef>
116 <function>lwres_buffer_back</function></funcdef>
117 <paramdef>lwres_buffer_t *b</paramdef>
118 <paramdef>unsigned int n</paramdef>
124 <function>lwres_buffer_getuint8</function></funcdef>
125 <paramdef>lwres_buffer_t *b</paramdef>
131 <function>lwres_buffer_putuint8</function></funcdef>
132 <paramdef>lwres_buffer_t *b</paramdef>
133 <paramdef>lwres_uint8_t val</paramdef>
139 <function>lwres_buffer_getuint16</function></funcdef>
140 <paramdef>lwres_buffer_t *b</paramdef>
146 <function>lwres_buffer_putuint16</function></funcdef>
147 <paramdef>lwres_buffer_t *b</paramdef>
148 <paramdef>lwres_uint16_t val</paramdef>
154 <function>lwres_buffer_getuint32</function></funcdef>
155 <paramdef>lwres_buffer_t *b</paramdef>
161 <function>lwres_buffer_putuint32</function></funcdef>
162 <paramdef>lwres_buffer_t *b</paramdef>
163 <paramdef>lwres_uint32_t val</paramdef>
169 <function>lwres_buffer_putmem</function></funcdef>
170 <paramdef>lwres_buffer_t *b</paramdef>
171 <paramdef>const unsigned char *base</paramdef>
172 <paramdef>unsigned int length</paramdef>
178 <function>lwres_buffer_getmem</function></funcdef>
179 <paramdef>lwres_buffer_t *b</paramdef>
180 <paramdef>unsigned char *base</paramdef>
181 <paramdef>unsigned int length</paramdef>
189 <title>DESCRIPTION</title>
191 These functions provide bounds checked access to a region of memory
192 where data is being read or written.
193 They are based on, and similar to, the
194 <literal>isc_buffer_</literal>
195 functions in the ISC library.
198 A buffer is a region of memory, together with a set of related
200 The <emphasis>used region</emphasis> and the
201 <emphasis>available</emphasis> region are disjoint, and
202 their union is the buffer's region.
203 The used region extends from the beginning of the buffer region to the
205 The available region extends from one byte greater than the last used
206 byte to the end of the buffer's region.
207 The size of the used region can be changed using various
209 Initially, the used region is empty.
212 The used region is further subdivided into two disjoint regions: the
213 <emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
214 The union of these two regions is the used region.
215 The consumed region extends from the beginning of the used region to
216 the byte before the <emphasis>current</emphasis> offset (if any).
217 The <emphasis>remaining</emphasis> region the current pointer to the end of the used
219 The size of the consumed region can be changed using various
221 Initially, the consumed region is empty.
224 The <emphasis>active region</emphasis> is an (optional) subregion of the remaining
226 It extends from the current offset to an offset in the
228 Initially, the active region is empty.
229 If the current offset advances beyond the chosen offset,
230 the active region will also be empty.
235 /------------entire length---------------\\
236 /----- used region -----\\/-- available --\\
237 +----------------------------------------+
238 | consumed | remaining | |
239 +----------------------------------------+
243 b == current pointer. Can be anywhere between a and d.
244 c == active pointer. Meaningful between b and d.
246 e == length of buffer.
248 a-e == entire length of buffer.
250 a-b == consumed region.
251 b-d == remaining region.
252 b-c == optional active region.
256 <function>lwres_buffer_init()</function>
258 <type>lwres_buffer_t</type>
259 <parameter>*b</parameter>
260 and assocates it with the memory region of size
261 <parameter>length</parameter>
262 bytes starting at location
263 <parameter>base.</parameter>
266 <function>lwres_buffer_invalidate()</function>
268 <parameter>*b</parameter>
269 as invalid. Invalidating a buffer after use is not required,
270 but makes it possible to catch its possible accidental use.
274 <function>lwres_buffer_add()</function>
276 <function>lwres_buffer_subtract()</function>
277 respectively increase and decrease the used space in
279 <parameter>*b</parameter>
281 <parameter>n</parameter>
283 <function>lwres_buffer_add()</function>
284 checks for buffer overflow and
285 <function>lwres_buffer_subtract()</function>
286 checks for underflow.
287 These functions do not allocate or deallocate memory.
288 They just change the value of
289 <structfield>used</structfield>.
292 A buffer is re-initialised by
293 <function>lwres_buffer_clear()</function>.
295 <structfield>used</structfield> ,
296 <structfield>current</structfield>
298 <structfield>active</structfield>
302 <function>lwres_buffer_first</function>
303 makes the consumed region of buffer
304 <parameter>*p</parameter>
306 <structfield>current</structfield>
307 to zero (the start of the buffer).
310 <function>lwres_buffer_forward()</function>
311 increases the consumed region of buffer
312 <parameter>*b</parameter>
314 <parameter>n</parameter>
315 bytes, checking for overflow.
317 <function>lwres_buffer_back()</function>
319 <parameter>b</parameter>'s
321 <parameter>n</parameter>
322 bytes and checks for underflow.
325 <function>lwres_buffer_getuint8()</function>
326 reads an unsigned 8-bit integer from
327 <parameter>*b</parameter>
329 <function>lwres_buffer_putuint8()</function>
330 writes the unsigned 8-bit integer
331 <parameter>val</parameter>
333 <parameter>*b</parameter>.
336 <function>lwres_buffer_getuint16()</function>
338 <function>lwres_buffer_getuint32()</function>
340 <function>lwres_buffer_putuint8()</function>
341 except that they respectively read an unsigned 16-bit or 32-bit integer
342 in network byte order from
343 <parameter>b</parameter>.
345 <function>lwres_buffer_putuint16()</function>
347 <function>lwres_buffer_putuint32()</function>
348 writes the unsigned 16-bit or 32-bit integer
349 <parameter>val</parameter>
351 <parameter>b</parameter>,
352 in network byte order.
355 Arbitrary amounts of data are read or written from a lightweight
357 <function>lwres_buffer_getmem()</function>
359 <function>lwres_buffer_putmem()</function>
361 <function>lwres_buffer_putmem()</function>
363 <parameter>length</parameter>
365 <parameter>base</parameter>
367 <parameter>b</parameter>.
369 <function>lwres_buffer_getmem()</function>
371 <parameter>length</parameter>
373 <parameter>b</parameter>
375 <parameter>base</parameter>.