2 - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
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 ISC DISCLAIMS ALL WARRANTIES WITH
10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 - PERFORMANCE OF THIS SOFTWARE.
18 <!-- $Id: lwres_buffer.html,v 1.4.2.2 2004/03/15 04:45:00 marka Exp $ -->
26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
47 >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</DIV
49 CLASS="REFSYNOPSISDIV"
63 CLASS="FUNCSYNOPSISINFO"
64 >#include <lwres/lwbuffer.h></PRE
70 lwres_buffer_init</CODE
71 >(lwres_buffer_t *b, void *base, unsigned int length);</CODE
78 lwres_buffer_invalidate</CODE
79 >(lwres_buffer_t *b);</CODE
86 lwres_buffer_add</CODE
87 >(lwres_buffer_t *b, unsigned int n);</CODE
94 lwres_buffer_subtract</CODE
95 >(lwres_buffer_t *b, unsigned int n);</CODE
102 lwres_buffer_clear</CODE
103 >(lwres_buffer_t *b);</CODE
110 lwres_buffer_first</CODE
111 >(lwres_buffer_t *b);</CODE
118 lwres_buffer_forward</CODE
119 >(lwres_buffer_t *b, unsigned int n);</CODE
126 lwres_buffer_back</CODE
127 >(lwres_buffer_t *b, unsigned int n);</CODE
134 lwres_buffer_getuint8</CODE
135 >(lwres_buffer_t *b);</CODE
142 lwres_buffer_putuint8</CODE
143 >(lwres_buffer_t *b, lwres_uint8_t val);</CODE
150 lwres_buffer_getuint16</CODE
151 >(lwres_buffer_t *b);</CODE
158 lwres_buffer_putuint16</CODE
159 >(lwres_buffer_t *b, lwres_uint16_t val);</CODE
166 lwres_buffer_getuint32</CODE
167 >(lwres_buffer_t *b);</CODE
174 lwres_buffer_putuint32</CODE
175 >(lwres_buffer_t *b, lwres_uint32_t val);</CODE
182 lwres_buffer_putmem</CODE
183 >(lwres_buffer_t *b, const unsigned char *base, unsigned int length);</CODE
190 lwres_buffer_getmem</CODE
191 >(lwres_buffer_t *b, unsigned char *base, unsigned int length);</CODE
205 >These functions provide bounds checked access to a region of memory
206 where data is being read or written.
207 They are based on, and similar to, the
212 functions in the ISC library.</P
214 >A buffer is a region of memory, together with a set of related
229 > region are disjoint, and
230 their union is the buffer's region.
231 The used region extends from the beginning of the buffer region to the
233 The available region extends from one byte greater than the last used
234 byte to the end of the buffer's region.
235 The size of the used region can be changed using various
237 Initially, the used region is empty.</P
239 >The used region is further subdivided into two disjoint regions: the
253 The union of these two regions is the used region.
254 The consumed region extends from the beginning of the used region to
255 the byte before the <SPAN
268 > region the current pointer to the end of the used
270 The size of the consumed region can be changed using various
272 Initially, the consumed region is empty.</P
280 > is an (optional) subregion of the remaining
282 It extends from the current offset to an offset in the
284 Initially, the active region is empty.
285 If the current offset advances beyond the chosen offset,
286 the active region will also be empty.</P
289 CLASS="PROGRAMLISTING"
291 /------------entire length---------------\\
292 /----- used region -----\\/-- available --\\
293 +----------------------------------------+
294 | consumed | remaining | |
295 +----------------------------------------+
299 b == current pointer. Can be anywhere between a and d.
300 c == active pointer. Meaningful between b and d.
302 e == length of buffer.
304 a-e == entire length of buffer.
306 a-b == consumed region.
307 b-d == remaining region.
308 b-c == optional active region.</PRE
313 >lwres_buffer_init()</TT
318 >lwres_buffer_t</SPAN
326 and assocates it with the memory region of size
333 bytes starting at location
343 >lwres_buffer_invalidate()</TT
352 as invalid. Invalidating a buffer after use is not required,
353 but makes it possible to catch its possible accidental use.</P
358 >lwres_buffer_add()</TT
363 >lwres_buffer_subtract()</TT
365 respectively increase and decrease the used space in
383 >lwres_buffer_add()</TT
385 checks for buffer overflow and
388 >lwres_buffer_subtract()</TT
390 checks for underflow.
391 These functions do not allocate or deallocate memory.
392 They just change the value of
400 >A buffer is re-initialised by
403 >lwres_buffer_clear()</TT
429 >lwres_buffer_first</TT
431 makes the consumed region of buffer
445 to zero (the start of the buffer).</P
449 >lwres_buffer_forward()</TT
451 increases the consumed region of buffer
465 bytes, checking for overflow.
469 >lwres_buffer_back()</TT
485 bytes and checks for underflow.</P
489 >lwres_buffer_getuint8()</TT
491 reads an unsigned 8-bit integer from
501 >lwres_buffer_putuint8()</TT
503 writes the unsigned 8-bit integer
520 >lwres_buffer_getuint16()</TT
525 >lwres_buffer_getuint32()</TT
530 >lwres_buffer_putuint8()</TT
532 except that they respectively read an unsigned 16-bit or 32-bit integer
533 in network byte order from
543 >lwres_buffer_putuint16()</TT
548 >lwres_buffer_putuint32()</TT
550 writes the unsigned 16-bit or 32-bit integer
564 in network byte order.</P
566 >Arbitrary amounts of data are read or written from a lightweight
570 >lwres_buffer_getmem()</TT
575 >lwres_buffer_putmem()</TT
580 >lwres_buffer_putmem()</TT
606 >lwres_buffer_getmem()</TT