]>
Commit | Line | Data |
---|---|---|
997358a6 MW |
1 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> |
2 | <!-- | |
3 | - Copyright (C) 2001 Internet Software Consortium. | |
4 | - | |
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. | |
8 | - | |
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. | |
17 | --> | |
18 | ||
19 | <!-- $Id: lwres_buffer.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ --> | |
20 | ||
21 | <refentry> | |
22 | <refentryinfo> | |
23 | <date>Jun 30, 2000</date> | |
24 | </refentryinfo> | |
25 | ||
26 | <refmeta> | |
27 | <refentrytitle>lwres_buffer</refentrytitle> | |
28 | <manvolnum>3</manvolnum> | |
29 | <refmiscinfo>BIND9</refmiscinfo> | |
30 | </refmeta> | |
31 | ||
32 | <refnamediv> | |
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> | |
50 | </refnamediv> | |
51 | ||
52 | <refsynopsisdiv> | |
53 | ||
54 | <funcsynopsis> | |
55 | <funcsynopsisinfo> | |
56 | #include <lwres/lwbuffer.h> | |
57 | </funcsynopsisinfo> | |
58 | ||
59 | <funcprototype> | |
60 | ||
61 | <funcdef> | |
62 | void | |
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> | |
67 | </funcprototype> | |
68 | ||
69 | <funcprototype> | |
70 | <funcdef> | |
71 | void | |
72 | <function>lwres_buffer_invalidate</function></funcdef> | |
73 | <paramdef>lwres_buffer_t *b</paramdef> | |
74 | </funcprototype> | |
75 | <funcprototype> | |
76 | <funcdef> | |
77 | void | |
78 | <function>lwres_buffer_add</function></funcdef> | |
79 | <paramdef>lwres_buffer_t *b</paramdef> | |
80 | <paramdef>unsigned int n</paramdef> | |
81 | </funcprototype> | |
82 | ||
83 | <funcprototype> | |
84 | <funcdef> | |
85 | void | |
86 | <function>lwres_buffer_subtract</function></funcdef> | |
87 | <paramdef>lwres_buffer_t *b</paramdef> | |
88 | <paramdef>unsigned int n</paramdef> | |
89 | </funcprototype> | |
90 | ||
91 | <funcprototype> | |
92 | <funcdef> | |
93 | void | |
94 | <function>lwres_buffer_clear</function></funcdef> | |
95 | <paramdef>lwres_buffer_t *b</paramdef> | |
96 | </funcprototype> | |
97 | ||
98 | <funcprototype> | |
99 | <funcdef> | |
100 | void | |
101 | <function>lwres_buffer_first</function></funcdef> | |
102 | <paramdef>lwres_buffer_t *b</paramdef> | |
103 | </funcprototype> | |
104 | ||
105 | <funcprototype> | |
106 | <funcdef> | |
107 | void | |
108 | <function>lwres_buffer_forward</function></funcdef> | |
109 | <paramdef>lwres_buffer_t *b</paramdef> | |
110 | <paramdef>unsigned int n</paramdef> | |
111 | </funcprototype> | |
112 | <funcprototype> | |
113 | ||
114 | <funcdef> | |
115 | void | |
116 | <function>lwres_buffer_back</function></funcdef> | |
117 | <paramdef>lwres_buffer_t *b</paramdef> | |
118 | <paramdef>unsigned int n</paramdef> | |
119 | </funcprototype> | |
120 | ||
121 | <funcprototype> | |
122 | <funcdef> | |
123 | lwres_uint8_t | |
124 | <function>lwres_buffer_getuint8</function></funcdef> | |
125 | <paramdef>lwres_buffer_t *b</paramdef> | |
126 | </funcprototype> | |
127 | ||
128 | <funcprototype> | |
129 | <funcdef> | |
130 | void | |
131 | <function>lwres_buffer_putuint8</function></funcdef> | |
132 | <paramdef>lwres_buffer_t *b</paramdef> | |
133 | <paramdef>lwres_uint8_t val</paramdef> | |
134 | </funcprototype> | |
135 | ||
136 | <funcprototype> | |
137 | <funcdef> | |
138 | lwres_uint16_t | |
139 | <function>lwres_buffer_getuint16</function></funcdef> | |
140 | <paramdef>lwres_buffer_t *b</paramdef> | |
141 | </funcprototype> | |
142 | ||
143 | <funcprototype> | |
144 | <funcdef> | |
145 | void | |
146 | <function>lwres_buffer_putuint16</function></funcdef> | |
147 | <paramdef>lwres_buffer_t *b</paramdef> | |
148 | <paramdef>lwres_uint16_t val</paramdef> | |
149 | </funcprototype> | |
150 | ||
151 | <funcprototype> | |
152 | <funcdef> | |
153 | lwres_uint32_t | |
154 | <function>lwres_buffer_getuint32</function></funcdef> | |
155 | <paramdef>lwres_buffer_t *b</paramdef> | |
156 | </funcprototype> | |
157 | ||
158 | <funcprototype> | |
159 | <funcdef> | |
160 | void | |
161 | <function>lwres_buffer_putuint32</function></funcdef> | |
162 | <paramdef>lwres_buffer_t *b</paramdef> | |
163 | <paramdef>lwres_uint32_t val</paramdef> | |
164 | </funcprototype> | |
165 | ||
166 | <funcprototype> | |
167 | <funcdef> | |
168 | void | |
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> | |
173 | </funcprototype> | |
174 | ||
175 | <funcprototype> | |
176 | <funcdef> | |
177 | void | |
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> | |
182 | </funcprototype> | |
183 | ||
184 | </funcsynopsis> | |
185 | </refsynopsisdiv> | |
186 | ||
187 | <refsect1> | |
188 | ||
189 | <title>DESCRIPTION</title> | |
190 | <para> | |
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. | |
196 | </para> | |
197 | <para> | |
198 | A buffer is a region of memory, together with a set of related | |
199 | subregions. | |
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 | |
204 | last used byte. | |
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 | |
208 | buffer commands. | |
209 | Initially, the used region is empty. | |
210 | </para> | |
211 | <para> | |
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 | |
218 | region. | |
219 | The size of the consumed region can be changed using various | |
220 | buffer commands. | |
221 | Initially, the consumed region is empty. | |
222 | </para> | |
223 | <para> | |
224 | The <emphasis>active region</emphasis> is an (optional) subregion of the remaining | |
225 | region. | |
226 | It extends from the current offset to an offset in the | |
227 | remaining region. | |
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. | |
231 | </para> | |
232 | <para> | |
233 | <programlisting> | |
234 | ||
235 | /------------entire length---------------\\ | |
236 | /----- used region -----\\/-- available --\\ | |
237 | +----------------------------------------+ | |
238 | | consumed | remaining | | | |
239 | +----------------------------------------+ | |
240 | a b c d e | |
241 | ||
242 | a == base of buffer. | |
243 | b == current pointer. Can be anywhere between a and d. | |
244 | c == active pointer. Meaningful between b and d. | |
245 | d == used pointer. | |
246 | e == length of buffer. | |
247 | ||
248 | a-e == entire length of buffer. | |
249 | a-d == used region. | |
250 | a-b == consumed region. | |
251 | b-d == remaining region. | |
252 | b-c == optional active region. | |
253 | </programlisting> | |
254 | </para> | |
255 | <para> | |
256 | <function>lwres_buffer_init()</function> | |
257 | initializes the | |
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> | |
264 | </para> | |
265 | <para> | |
266 | <function>lwres_buffer_invalidate()</function> | |
267 | marks the buffer | |
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. | |
271 | </para> | |
272 | <para> | |
273 | The functions | |
274 | <function>lwres_buffer_add()</function> | |
275 | and | |
276 | <function>lwres_buffer_subtract()</function> | |
277 | respectively increase and decrease the used space in | |
278 | buffer | |
279 | <parameter>*b</parameter> | |
280 | by | |
281 | <parameter>n</parameter> | |
282 | bytes. | |
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>. | |
290 | </para> | |
291 | <para> | |
292 | A buffer is re-initialised by | |
293 | <function>lwres_buffer_clear()</function>. | |
294 | The function sets | |
295 | <structfield>used</structfield> , | |
296 | <structfield>current</structfield> | |
297 | and | |
298 | <structfield>active</structfield> | |
299 | to zero. | |
300 | </para> | |
301 | <para> | |
302 | <function>lwres_buffer_first</function> | |
303 | makes the consumed region of buffer | |
304 | <parameter>*p</parameter> | |
305 | empty by setting | |
306 | <structfield>current</structfield> | |
307 | to zero (the start of the buffer). | |
308 | </para> | |
309 | <para> | |
310 | <function>lwres_buffer_forward()</function> | |
311 | increases the consumed region of buffer | |
312 | <parameter>*b</parameter> | |
313 | by | |
314 | <parameter>n</parameter> | |
315 | bytes, checking for overflow. | |
316 | Similarly, | |
317 | <function>lwres_buffer_back()</function> | |
318 | decreases buffer | |
319 | <parameter>b</parameter>'s | |
320 | consumed region by | |
321 | <parameter>n</parameter> | |
322 | bytes and checks for underflow. | |
323 | </para> | |
324 | <para> | |
325 | <function>lwres_buffer_getuint8()</function> | |
326 | reads an unsigned 8-bit integer from | |
327 | <parameter>*b</parameter> | |
328 | and returns it. | |
329 | <function>lwres_buffer_putuint8()</function> | |
330 | writes the unsigned 8-bit integer | |
331 | <parameter>val</parameter> | |
332 | to buffer | |
333 | <parameter>*b</parameter>. | |
334 | </para> | |
335 | <para> | |
336 | <function>lwres_buffer_getuint16()</function> | |
337 | and | |
338 | <function>lwres_buffer_getuint32()</function> | |
339 | are identical to | |
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>. | |
344 | Similarly, | |
345 | <function>lwres_buffer_putuint16()</function> | |
346 | and | |
347 | <function>lwres_buffer_putuint32()</function> | |
348 | writes the unsigned 16-bit or 32-bit integer | |
349 | <parameter>val</parameter> | |
350 | to buffer | |
351 | <parameter>b</parameter>, | |
352 | in network byte order. | |
353 | </para> | |
354 | <para> | |
355 | Arbitrary amounts of data are read or written from a lightweight | |
356 | resolver buffer with | |
357 | <function>lwres_buffer_getmem()</function> | |
358 | and | |
359 | <function>lwres_buffer_putmem()</function> | |
360 | respectively. | |
361 | <function>lwres_buffer_putmem()</function> | |
362 | copies | |
363 | <parameter>length</parameter> | |
364 | bytes of memory at | |
365 | <parameter>base</parameter> | |
366 | to | |
367 | <parameter>b</parameter>. | |
368 | Conversely, | |
369 | <function>lwres_buffer_getmem()</function> | |
370 | copies | |
371 | <parameter>length</parameter> | |
372 | bytes of memory from | |
373 | <parameter>b</parameter> | |
374 | to | |
375 | <parameter>base</parameter>. | |
376 | </para> | |
377 | </refsect1> | |
378 | </refentry> |