48
<refname>lwres_buffer_init</refname>
49
<refname>lwres_buffer_invalidate</refname>
50
<refname>lwres_buffer_add</refname>
51
<refname>lwres_buffer_subtract</refname>
52
<refname>lwres_buffer_clear</refname>
53
<refname>lwres_buffer_first</refname>
54
<refname>lwres_buffer_forward</refname>
55
<refname>lwres_buffer_back</refname>
56
<refname>lwres_buffer_getuint8</refname>
57
<refname>lwres_buffer_putuint8</refname>
58
<refname>lwres_buffer_getuint16</refname>
59
<refname>lwres_buffer_putuint16</refname>
60
<refname>lwres_buffer_getuint32</refname>
61
<refname>lwres_buffer_putuint32</refname>
62
<refname>lwres_buffer_putmem</refname>
63
<refname>lwres_buffer_getmem</refname>
64
<refpurpose>lightweight resolver buffer management</refpurpose>
48
<refname>lwres_buffer_init</refname>
49
<refname>lwres_buffer_invalidate</refname>
50
<refname>lwres_buffer_add</refname>
51
<refname>lwres_buffer_subtract</refname>
52
<refname>lwres_buffer_clear</refname>
53
<refname>lwres_buffer_first</refname>
54
<refname>lwres_buffer_forward</refname>
55
<refname>lwres_buffer_back</refname>
56
<refname>lwres_buffer_getuint8</refname>
57
<refname>lwres_buffer_putuint8</refname>
58
<refname>lwres_buffer_getuint16</refname>
59
<refname>lwres_buffer_putuint16</refname>
60
<refname>lwres_buffer_getuint32</refname>
61
<refname>lwres_buffer_putuint32</refname>
62
<refname>lwres_buffer_putmem</refname>
63
<refname>lwres_buffer_getmem</refname>
64
<refpurpose>lightweight resolver buffer management</refpurpose>
71
71
#include <lwres/lwbuffer.h>
72
72
</funcsynopsisinfo>
78
78
<function>lwres_buffer_init</function></funcdef>
79
<paramdef>lwres_buffer_t *b</paramdef>
80
<paramdef>void *base</paramdef>
81
<paramdef>unsigned int length</paramdef>
79
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
80
<paramdef>void *<parameter>base</parameter></paramdef>
81
<paramdef>unsigned int <parameter>length</parameter></paramdef>
87
87
<function>lwres_buffer_invalidate</function></funcdef>
88
<paramdef>lwres_buffer_t *b</paramdef>
88
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
93
93
<function>lwres_buffer_add</function></funcdef>
94
<paramdef>lwres_buffer_t *b</paramdef>
95
<paramdef>unsigned int n</paramdef>
94
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
95
<paramdef>unsigned int <parameter>n</parameter></paramdef>
101
101
<function>lwres_buffer_subtract</function></funcdef>
102
<paramdef>lwres_buffer_t *b</paramdef>
103
<paramdef>unsigned int n</paramdef>
102
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
103
<paramdef>unsigned int <parameter>n</parameter></paramdef>
109
109
<function>lwres_buffer_clear</function></funcdef>
110
<paramdef>lwres_buffer_t *b</paramdef>
110
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
116
116
<function>lwres_buffer_first</function></funcdef>
117
<paramdef>lwres_buffer_t *b</paramdef>
117
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
123
123
<function>lwres_buffer_forward</function></funcdef>
124
<paramdef>lwres_buffer_t *b</paramdef>
125
<paramdef>unsigned int n</paramdef>
124
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
125
<paramdef>unsigned int <parameter>n</parameter></paramdef>
131
131
<function>lwres_buffer_back</function></funcdef>
132
<paramdef>lwres_buffer_t *b</paramdef>
133
<paramdef>unsigned int n</paramdef>
132
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
133
<paramdef>unsigned int <parameter>n</parameter></paramdef>
139
139
<function>lwres_buffer_getuint8</function></funcdef>
140
<paramdef>lwres_buffer_t *b</paramdef>
140
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
146
146
<function>lwres_buffer_putuint8</function></funcdef>
147
<paramdef>lwres_buffer_t *b</paramdef>
148
<paramdef>lwres_uint8_t val</paramdef>
147
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
148
<paramdef>lwres_uint8_t <parameter>val</parameter></paramdef>
154
154
<function>lwres_buffer_getuint16</function></funcdef>
155
<paramdef>lwres_buffer_t *b</paramdef>
155
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
161
161
<function>lwres_buffer_putuint16</function></funcdef>
162
<paramdef>lwres_buffer_t *b</paramdef>
163
<paramdef>lwres_uint16_t val</paramdef>
162
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
163
<paramdef>lwres_uint16_t <parameter>val</parameter></paramdef>
169
169
<function>lwres_buffer_getuint32</function></funcdef>
170
<paramdef>lwres_buffer_t *b</paramdef>
170
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
176
176
<function>lwres_buffer_putuint32</function></funcdef>
177
<paramdef>lwres_buffer_t *b</paramdef>
178
<paramdef>lwres_uint32_t val</paramdef>
177
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
178
<paramdef>lwres_uint32_t <parameter>val</parameter></paramdef>
184
184
<function>lwres_buffer_putmem</function></funcdef>
185
<paramdef>lwres_buffer_t *b</paramdef>
186
<paramdef>const unsigned char *base</paramdef>
187
<paramdef>unsigned int length</paramdef>
185
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
186
<paramdef>const unsigned char *<parameter>base</parameter></paramdef>
187
<paramdef>unsigned int <parameter>length</parameter></paramdef>
193
193
<function>lwres_buffer_getmem</function></funcdef>
194
<paramdef>lwres_buffer_t *b</paramdef>
195
<paramdef>unsigned char *base</paramdef>
196
<paramdef>unsigned int length</paramdef>
194
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
195
<paramdef>unsigned char *<parameter>base</parameter></paramdef>
196
<paramdef>unsigned int <parameter>length</parameter></paramdef>
204
<title>DESCRIPTION</title>
206
These functions provide bounds checked access to a region of memory
207
where data is being read or written.
208
They are based on, and similar to, the
209
<literal>isc_buffer_</literal>
210
functions in the ISC library.
213
A buffer is a region of memory, together with a set of related
215
The <emphasis>used region</emphasis> and the
216
<emphasis>available</emphasis> region are disjoint, and
217
their union is the buffer's region.
218
The used region extends from the beginning of the buffer region to the
220
The available region extends from one byte greater than the last used
221
byte to the end of the buffer's region.
222
The size of the used region can be changed using various
224
Initially, the used region is empty.
227
The used region is further subdivided into two disjoint regions: the
228
<emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
229
The union of these two regions is the used region.
230
The consumed region extends from the beginning of the used region to
231
the byte before the <emphasis>current</emphasis> offset (if any).
232
The <emphasis>remaining</emphasis> region the current pointer to the end of the used
234
The size of the consumed region can be changed using various
236
Initially, the consumed region is empty.
239
The <emphasis>active region</emphasis> is an (optional) subregion of the remaining
241
It extends from the current offset to an offset in the
243
Initially, the active region is empty.
244
If the current offset advances beyond the chosen offset,
245
the active region will also be empty.
204
<title>DESCRIPTION</title>
206
These functions provide bounds checked access to a region of memory
207
where data is being read or written.
208
They are based on, and similar to, the
209
<literal>isc_buffer_</literal>
210
functions in the ISC library.
213
A buffer is a region of memory, together with a set of related
215
The <emphasis>used region</emphasis> and the
216
<emphasis>available</emphasis> region are disjoint, and
217
their union is the buffer's region.
218
The used region extends from the beginning of the buffer region to the
220
The available region extends from one byte greater than the last used
221
byte to the end of the buffer's region.
222
The size of the used region can be changed using various
224
Initially, the used region is empty.
227
The used region is further subdivided into two disjoint regions: the
228
<emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
229
The union of these two regions is the used region.
230
The consumed region extends from the beginning of the used region to
231
the byte before the <emphasis>current</emphasis> offset (if any).
232
The <emphasis>remaining</emphasis> region the current pointer to the end
235
The size of the consumed region can be changed using various
237
Initially, the consumed region is empty.
240
The <emphasis>active region</emphasis> is an (optional) subregion of the
243
It extends from the current offset to an offset in the
245
Initially, the active region is empty.
246
If the current offset advances beyond the chosen offset,
247
the active region will also be empty.
249
<para><programlisting>
250
250
/------------entire length---------------\\
251
251
/----- used region -----\\/-- available --\\
252
252
+----------------------------------------+
253
253
| consumed | remaining | |
254
254
+----------------------------------------+
258
<para><programlisting>
257
259
a == base of buffer.
258
260
b == current pointer. Can be anywhere between a and d.
259
261
c == active pointer. Meaningful between b and d.
260
262
d == used pointer.
261
263
e == length of buffer.
266
<para><programlisting>
263
267
a-e == entire length of buffer.
264
268
a-d == used region.
265
269
a-b == consumed region.
266
270
b-d == remaining region.
267
271
b-c == optional active region.
268
272
</programlisting>
271
<function>lwres_buffer_init()</function>
273
<type>lwres_buffer_t</type>
274
<parameter>*b</parameter>
275
and assocates it with the memory region of size
276
<parameter>length</parameter>
277
bytes starting at location
278
<parameter>base.</parameter>
281
<function>lwres_buffer_invalidate()</function>
283
<parameter>*b</parameter>
284
as invalid. Invalidating a buffer after use is not required,
285
but makes it possible to catch its possible accidental use.
289
<function>lwres_buffer_add()</function>
291
<function>lwres_buffer_subtract()</function>
292
respectively increase and decrease the used space in
294
<parameter>*b</parameter>
296
<parameter>n</parameter>
298
<function>lwres_buffer_add()</function>
299
checks for buffer overflow and
300
<function>lwres_buffer_subtract()</function>
301
checks for underflow.
302
These functions do not allocate or deallocate memory.
303
They just change the value of
304
<structfield>used</structfield>.
307
A buffer is re-initialised by
308
<function>lwres_buffer_clear()</function>.
310
<structfield>used</structfield> ,
311
<structfield>current</structfield>
313
<structfield>active</structfield>
317
<function>lwres_buffer_first</function>
318
makes the consumed region of buffer
319
<parameter>*p</parameter>
321
<structfield>current</structfield>
322
to zero (the start of the buffer).
325
<function>lwres_buffer_forward()</function>
326
increases the consumed region of buffer
327
<parameter>*b</parameter>
329
<parameter>n</parameter>
330
bytes, checking for overflow.
332
<function>lwres_buffer_back()</function>
334
<parameter>b</parameter>'s
336
<parameter>n</parameter>
337
bytes and checks for underflow.
340
<function>lwres_buffer_getuint8()</function>
341
reads an unsigned 8-bit integer from
342
<parameter>*b</parameter>
344
<function>lwres_buffer_putuint8()</function>
345
writes the unsigned 8-bit integer
346
<parameter>val</parameter>
348
<parameter>*b</parameter>.
351
<function>lwres_buffer_getuint16()</function>
353
<function>lwres_buffer_getuint32()</function>
355
<function>lwres_buffer_putuint8()</function>
356
except that they respectively read an unsigned 16-bit or 32-bit integer
357
in network byte order from
358
<parameter>b</parameter>.
360
<function>lwres_buffer_putuint16()</function>
362
<function>lwres_buffer_putuint32()</function>
363
writes the unsigned 16-bit or 32-bit integer
364
<parameter>val</parameter>
366
<parameter>b</parameter>,
367
in network byte order.
370
Arbitrary amounts of data are read or written from a lightweight
372
<function>lwres_buffer_getmem()</function>
374
<function>lwres_buffer_putmem()</function>
376
<function>lwres_buffer_putmem()</function>
378
<parameter>length</parameter>
380
<parameter>base</parameter>
382
<parameter>b</parameter>.
384
<function>lwres_buffer_getmem()</function>
386
<parameter>length</parameter>
388
<parameter>b</parameter>
390
<parameter>base</parameter>.
274
<para><function>lwres_buffer_init()</function>
276
<type>lwres_buffer_t</type>
277
<parameter>*b</parameter>
278
and assocates it with the memory region of size
279
<parameter>length</parameter>
280
bytes starting at location
281
<parameter>base.</parameter>
283
<para><function>lwres_buffer_invalidate()</function>
284
marks the buffer <parameter>*b</parameter>
285
as invalid. Invalidating a buffer after use is not required,
286
but makes it possible to catch its possible accidental use.
290
<function>lwres_buffer_add()</function>
292
<function>lwres_buffer_subtract()</function>
293
respectively increase and decrease the used space in
295
<parameter>*b</parameter>
297
<parameter>n</parameter>
299
<function>lwres_buffer_add()</function>
300
checks for buffer overflow and
301
<function>lwres_buffer_subtract()</function>
302
checks for underflow.
303
These functions do not allocate or deallocate memory.
304
They just change the value of
305
<structfield>used</structfield>.
308
A buffer is re-initialised by
309
<function>lwres_buffer_clear()</function>.
311
<structfield>used</structfield>,
312
<structfield>current</structfield>
314
<structfield>active</structfield>
317
<para><function>lwres_buffer_first</function>
318
makes the consumed region of buffer
319
<parameter>*p</parameter>
321
<structfield>current</structfield>
322
to zero (the start of the buffer).
324
<para><function>lwres_buffer_forward()</function>
325
increases the consumed region of buffer
326
<parameter>*b</parameter>
328
<parameter>n</parameter>
329
bytes, checking for overflow.
331
<function>lwres_buffer_back()</function>
333
<parameter>b</parameter>'s
335
<parameter>n</parameter>
336
bytes and checks for underflow.
338
<para><function>lwres_buffer_getuint8()</function>
339
reads an unsigned 8-bit integer from
340
<parameter>*b</parameter>
342
<function>lwres_buffer_putuint8()</function>
343
writes the unsigned 8-bit integer
344
<parameter>val</parameter>
346
<parameter>*b</parameter>.
348
<para><function>lwres_buffer_getuint16()</function>
350
<function>lwres_buffer_getuint32()</function>
352
<function>lwres_buffer_putuint8()</function>
353
except that they respectively read an unsigned 16-bit or 32-bit integer
354
in network byte order from
355
<parameter>b</parameter>.
357
<function>lwres_buffer_putuint16()</function>
359
<function>lwres_buffer_putuint32()</function>
360
writes the unsigned 16-bit or 32-bit integer
361
<parameter>val</parameter>
363
<parameter>b</parameter>,
364
in network byte order.
367
Arbitrary amounts of data are read or written from a lightweight
369
<function>lwres_buffer_getmem()</function>
371
<function>lwres_buffer_putmem()</function>
373
<function>lwres_buffer_putmem()</function>
375
<parameter>length</parameter>
377
<parameter>base</parameter>
379
<parameter>b</parameter>.
381
<function>lwres_buffer_getmem()</function>
383
<parameter>length</parameter>
385
<parameter>b</parameter>
387
<parameter>base</parameter>.
added
removed
lib/lwres/man/lwres_buffer.docbook
