contrib/bind-9.2.4rc7/lib/lwres/man/lwres_buffer.3

   1 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
   9 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  10 .\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  11 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  12 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  13 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  14 .\" PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .\" $Id: lwres_buffer.3,v 1.12.2.2 2004/03/15 04:45:00 marka Exp $
  17 .\"
  18 .TH "LWRES_BUFFER" "3" "Jun 30, 2000" "BIND9" ""
  19 .SH NAME
  20 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
  21 .SH SYNOPSIS
  22 \fB#include <lwres/lwbuffer.h>
  23 .sp
  24 .na
  25 void
  26 lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length);
  27 .ad
  28 .sp
  29 .na
  30 void
  31 lwres_buffer_invalidate(lwres_buffer_t *b);
  32 .ad
  33 .sp
  34 .na
  35 void
  36 lwres_buffer_add(lwres_buffer_t *b, unsigned int n);
  37 .ad
  38 .sp
  39 .na
  40 void
  41 lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n);
  42 .ad
  43 .sp
  44 .na
  45 void
  46 lwres_buffer_clear(lwres_buffer_t *b);
  47 .ad
  48 .sp
  49 .na
  50 void
  51 lwres_buffer_first(lwres_buffer_t *b);
  52 .ad
  53 .sp
  54 .na
  55 void
  56 lwres_buffer_forward(lwres_buffer_t *b, unsigned int n);
  57 .ad
  58 .sp
  59 .na
  60 void
  61 lwres_buffer_back(lwres_buffer_t *b, unsigned int n);
  62 .ad
  63 .sp
  64 .na
  65 lwres_uint8_t
  66 lwres_buffer_getuint8(lwres_buffer_t *b);
  67 .ad
  68 .sp
  69 .na
  70 void
  71 lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val);
  72 .ad
  73 .sp
  74 .na
  75 lwres_uint16_t
  76 lwres_buffer_getuint16(lwres_buffer_t *b);
  77 .ad
  78 .sp
  79 .na
  80 void
  81 lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val);
  82 .ad
  83 .sp
  84 .na
  85 lwres_uint32_t
  86 lwres_buffer_getuint32(lwres_buffer_t *b);
  87 .ad
  88 .sp
  89 .na
  90 void
  91 lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val);
  92 .ad
  93 .sp
  94 .na
  95 void
  96 lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base, unsigned int length);
  97 .ad
  98 .sp
  99 .na
 100 void
 101 lwres_buffer_getmem(lwres_buffer_t *b, unsigned char *base, unsigned int length);
 102 .ad
 103 \fR
 104 .SH "DESCRIPTION"
 105 .PP
 106 These functions provide bounds checked access to a region of memory
 107 where data is being read or written.
 108 They are based on, and similar to, the
 109 isc_buffer_
 110 functions in the ISC library.
 111 .PP
 112 A buffer is a region of memory, together with a set of related
 113 subregions.
 114 The \fBused region\fR and the
 115 \fBavailable\fR region are disjoint, and
 116 their union is the buffer's region.
 117 The used region extends from the beginning of the buffer region to the
 118 last used byte.
 119 The available region extends from one byte greater than the last used
 120 byte to the end of the buffer's region.
 121 The size of the used region can be changed using various
 122 buffer commands.
 123 Initially, the used region is empty.
 124 .PP
 125 The used region is further subdivided into two disjoint regions: the
 126 \fBconsumed region\fR and the \fBremaining region\fR.
 127 The union of these two regions is the used region.
 128 The consumed region extends from the beginning of the used region to
 129 the byte before the \fBcurrent\fR offset (if any).
 130 The \fBremaining\fR region the current pointer to the end of the used
 131 region.
 132 The size of the consumed region can be changed using various
 133 buffer commands.
 134 Initially, the consumed region is empty.
 135 .PP
 136 The \fBactive region\fR is an (optional) subregion of the remaining
 137 region.
 138 It extends from the current offset to an offset in the
 139 remaining region.
 140 Initially, the active region is empty.
 141 If the current offset advances beyond the chosen offset,
 142 the active region will also be empty.
 143 .PP
 144 .sp
 145 .nf
 146
 147    /------------entire length---------------\\\\
 148    /----- used region -----\\\\/-- available --\\\\
 149    +----------------------------------------+
 150    | consumed  | remaining |                |
 151    +----------------------------------------+
 152    a           b     c     d                e
 153
 154   a == base of buffer.
 155   b == current pointer.  Can be anywhere between a and d.
 156   c == active pointer.  Meaningful between b and d.
 157   d == used pointer.
 158   e == length of buffer.
 159
 160   a-e == entire length of buffer.
 161   a-d == used region.
 162   a-b == consumed region.
 163   b-d == remaining region.
 164   b-c == optional active region.
 165 .sp
 166 .fi
 167 .PP
 168 \fBlwres_buffer_init()\fR
 169 initializes the
 170 \fBlwres_buffer_t\fR
 171 \fI*b\fR
 172 and assocates it with the memory region of size
 173 \fIlength\fR
 174 bytes starting at location
 175 \fIbase.\fR
 176 .PP
 177 \fBlwres_buffer_invalidate()\fR
 178 marks the buffer
 179 \fI*b\fR
 180 as invalid. Invalidating a buffer after use is not required,
 181 but makes it possible to catch its possible accidental use.
 182 .PP
 183 The functions
 184 \fBlwres_buffer_add()\fR
 185 and
 186 \fBlwres_buffer_subtract()\fR
 187 respectively increase and decrease the used space in
 188 buffer
 189 \fI*b\fR
 190 by
 191 \fIn\fR
 192 bytes.
 193 \fBlwres_buffer_add()\fR
 194 checks for buffer overflow and
 195 \fBlwres_buffer_subtract()\fR
 196 checks for underflow.
 197 These functions do not allocate or deallocate memory.
 198 They just change the value of
 199 \fBused\fR.
 200 .PP
 201 A buffer is re-initialised by
 202 \fBlwres_buffer_clear()\fR.
 203 The function sets
 204 \fBused\fR ,
 205 \fBcurrent\fR
 206 and
 207 \fBactive\fR
 208 to zero.
 209 .PP
 210 \fBlwres_buffer_first\fR
 211 makes the consumed region of buffer
 212 \fI*p\fR
 213 empty by setting
 214 \fBcurrent\fR
 215 to zero (the start of the buffer).
 216 .PP
 217 \fBlwres_buffer_forward()\fR
 218 increases the consumed region of buffer
 219 \fI*b\fR
 220 by
 221 \fIn\fR
 222 bytes, checking for overflow.
 223 Similarly,
 224 \fBlwres_buffer_back()\fR
 225 decreases buffer
 226 \fIb\fR's
 227 consumed region by
 228 \fIn\fR
 229 bytes and checks for underflow.
 230 .PP
 231 \fBlwres_buffer_getuint8()\fR
 232 reads an unsigned 8-bit integer from
 233 \fI*b\fR
 234 and returns it.
 235 \fBlwres_buffer_putuint8()\fR
 236 writes the unsigned 8-bit integer
 237 \fIval\fR
 238 to buffer
 239 \fI*b\fR.
 240 .PP
 241 \fBlwres_buffer_getuint16()\fR
 242 and
 243 \fBlwres_buffer_getuint32()\fR
 244 are identical to
 245 \fBlwres_buffer_putuint8()\fR
 246 except that they respectively read an unsigned 16-bit or 32-bit integer
 247 in network byte order from
 248 \fIb\fR.
 249 Similarly,
 250 \fBlwres_buffer_putuint16()\fR
 251 and
 252 \fBlwres_buffer_putuint32()\fR
 253 writes the unsigned 16-bit or 32-bit integer
 254 \fIval\fR
 255 to buffer
 256 \fIb\fR,
 257 in network byte order.
 258 .PP
 259 Arbitrary amounts of data are read or written from a lightweight
 260 resolver buffer with
 261 \fBlwres_buffer_getmem()\fR
 262 and
 263 \fBlwres_buffer_putmem()\fR
 264 respectively.
 265 \fBlwres_buffer_putmem()\fR
 266 copies
 267 \fIlength\fR
 268 bytes of memory at
 269 \fIbase\fR
 270 to
 271 \fIb\fR.
 272 Conversely,
 273 \fBlwres_buffer_getmem()\fR
 274 copies
 275 \fIlength\fR
 276 bytes of memory from
 277 \fIb\fR
 278 to
 279 \fIbase\fR.