From f50ae72ec3417cae55dd4e085991c01af9fdc5f1 Mon Sep 17 00:00:00 2001 From: Martin Nagy Date: Wed, 11 Feb 2009 20:37:59 +0100 Subject: Initial commit --- lib/lwres/man/lwres_buffer.docbook | 394 +++++++++++++++++++++++++++++++++++++ 1 file changed, 394 insertions(+) create mode 100644 lib/lwres/man/lwres_buffer.docbook (limited to 'lib/lwres/man/lwres_buffer.docbook') diff --git a/lib/lwres/man/lwres_buffer.docbook b/lib/lwres/man/lwres_buffer.docbook new file mode 100644 index 0000000..97c52bd --- /dev/null +++ b/lib/lwres/man/lwres_buffer.docbook @@ -0,0 +1,394 @@ +]> + + + + + + Jun 30, 2000 + + + + lwres_buffer + 3 + BIND9 + + + + + 2004 + 2005 + 2007 + Internet Systems Consortium, Inc. ("ISC") + + + 2000 + 2001 + Internet Software Consortium. + + + + + 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 + + + + + + +#include <lwres/lwbuffer.h> + + + + + +void +lwres_buffer_init + lwres_buffer_t *b + void *base + unsigned int length + + + + +void +lwres_buffer_invalidate + lwres_buffer_t *b + + + +void +lwres_buffer_add + lwres_buffer_t *b + unsigned int n + + + + +void +lwres_buffer_subtract + lwres_buffer_t *b + unsigned int n + + + + +void +lwres_buffer_clear + lwres_buffer_t *b + + + + +void +lwres_buffer_first + lwres_buffer_t *b + + + + +void +lwres_buffer_forward + lwres_buffer_t *b + unsigned int n + + + + +void +lwres_buffer_back + lwres_buffer_t *b + unsigned int n + + + + +lwres_uint8_t +lwres_buffer_getuint8 + lwres_buffer_t *b + + + + +void +lwres_buffer_putuint8 + lwres_buffer_t *b + lwres_uint8_t val + + + + +lwres_uint16_t +lwres_buffer_getuint16 + lwres_buffer_t *b + + + + +void +lwres_buffer_putuint16 + lwres_buffer_t *b + lwres_uint16_t val + + + + +lwres_uint32_t +lwres_buffer_getuint32 + lwres_buffer_t *b + + + + +void +lwres_buffer_putuint32 + lwres_buffer_t *b + lwres_uint32_t val + + + + +void +lwres_buffer_putmem + lwres_buffer_t *b + const unsigned char *base + unsigned int length + + + + +void +lwres_buffer_getmem + lwres_buffer_t *b + unsigned char *base + unsigned int length + + + + + + + + DESCRIPTION + + These functions provide bounds checked access to a region of memory + where data is being read or written. + They are based on, and similar to, the + isc_buffer_ + functions in the ISC library. + + + A buffer is a region of memory, together with a set of related + subregions. + The used region and the + available region are disjoint, and + their union is the buffer's region. + The used region extends from the beginning of the buffer region to the + last used byte. + The available region extends from one byte greater than the last used + byte to the end of the buffer's region. + The size of the used region can be changed using various + buffer commands. + Initially, the used region is empty. + + + The used region is further subdivided into two disjoint regions: the + consumed region and the remaining region. + The union of these two regions is the used region. + The consumed region extends from the beginning of the used region to + the byte before the current offset (if any). + The remaining region the current pointer to the end + of the used + region. + The size of the consumed region can be changed using various + buffer commands. + Initially, the consumed region is empty. + + + The active region is an (optional) subregion of the + remaining + region. + It extends from the current offset to an offset in the + remaining region. + Initially, the active region is empty. + If the current offset advances beyond the chosen offset, + the active region will also be empty. + + + /------------entire length---------------\\ + /----- used region -----\\/-- available --\\ + +----------------------------------------+ + | consumed | remaining | | + +----------------------------------------+ + a b c d e + + + + a == base of buffer. + b == current pointer. Can be anywhere between a and d. + c == active pointer. Meaningful between b and d. + d == used pointer. + e == length of buffer. + + + + a-e == entire length of buffer. + a-d == used region. + a-b == consumed region. + b-d == remaining region. + b-c == optional active region. + + + lwres_buffer_init() + initializes the + lwres_buffer_t + *b + and assocates it with the memory region of size + length + bytes starting at location + base. + + lwres_buffer_invalidate() + marks the buffer *b + as invalid. Invalidating a buffer after use is not required, + but makes it possible to catch its possible accidental use. + + + The functions + lwres_buffer_add() + and + lwres_buffer_subtract() + respectively increase and decrease the used space in + buffer + *b + by + n + bytes. + lwres_buffer_add() + checks for buffer overflow and + lwres_buffer_subtract() + checks for underflow. + These functions do not allocate or deallocate memory. + They just change the value of + used. + + + A buffer is re-initialised by + lwres_buffer_clear(). + The function sets + used, + current + and + active + to zero. + + lwres_buffer_first + makes the consumed region of buffer + *p + empty by setting + current + to zero (the start of the buffer). + + lwres_buffer_forward() + increases the consumed region of buffer + *b + by + n + bytes, checking for overflow. + Similarly, + lwres_buffer_back() + decreases buffer + b's + consumed region by + n + bytes and checks for underflow. + + lwres_buffer_getuint8() + reads an unsigned 8-bit integer from + *b + and returns it. + lwres_buffer_putuint8() + writes the unsigned 8-bit integer + val + to buffer + *b. + + lwres_buffer_getuint16() + and + lwres_buffer_getuint32() + are identical to + lwres_buffer_putuint8() + except that they respectively read an unsigned 16-bit or 32-bit integer + in network byte order from + b. + Similarly, + lwres_buffer_putuint16() + and + lwres_buffer_putuint32() + writes the unsigned 16-bit or 32-bit integer + val + to buffer + b, + in network byte order. + + + Arbitrary amounts of data are read or written from a lightweight + resolver buffer with + lwres_buffer_getmem() + and + lwres_buffer_putmem() + respectively. + lwres_buffer_putmem() + copies + length + bytes of memory at + base + to + b. + Conversely, + lwres_buffer_getmem() + copies + length + bytes of memory from + b + to + base. + + + -- cgit