lib/liblwres/man/lwres_buffer.docbook

   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 &lt;lwres/lwbuffer.h&gt;
  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>