contrib/bind9/lib/lwres/man/lwres_buffer.docbook

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000, 2001  Internet Software Consortium.
   7  -
   8  - Permission to use, copy, modify, and distribute this software for any
   9  - purpose with or without fee is hereby granted, provided that the above
  10  - copyright notice and this permission notice appear in all copies.
  11  -
  12  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  13  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  14  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  15  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  16  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  17  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  18  - PERFORMANCE OF THIS SOFTWARE.
  19 -->
  20
  21 <!-- $Id: lwres_buffer.docbook,v 1.3.206.3 2005/05/12 21:36:11 sra Exp $ -->
  22
  23 <refentry>
  24 <refentryinfo>
  25 <date>Jun 30, 2000</date>
  26 </refentryinfo>
  27
  28 <refmeta>
  29 <refentrytitle>lwres_buffer</refentrytitle>
  30 <manvolnum>3</manvolnum>
  31 <refmiscinfo>BIND9</refmiscinfo>
  32 </refmeta>
  33
  34   <docinfo>
  35     <copyright>
  36       <year>2004</year>
  37       <year>2005</year>
  38       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  39     </copyright>
  40     <copyright>
  41       <year>2000</year>
  42       <year>2001</year>
  43       <holder>Internet Software Consortium.</holder>
  44     </copyright>
  45   </docinfo>
  46
  47 <refnamediv>
  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>
  65 </refnamediv>
  66
  67 <refsynopsisdiv>
  68
  69 <funcsynopsis>
  70 <funcsynopsisinfo>
  71 #include &lt;lwres/lwbuffer.h&gt;
  72 </funcsynopsisinfo>
  73
  74 <funcprototype>
  75
  76 <funcdef>
  77 void
  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>
  82 </funcprototype>
  83
  84 <funcprototype>
  85 <funcdef>
  86 void
  87 <function>lwres_buffer_invalidate</function></funcdef>
  88 <paramdef>lwres_buffer_t *b</paramdef>
  89 </funcprototype>
  90 <funcprototype>
  91 <funcdef>
  92 void
  93 <function>lwres_buffer_add</function></funcdef>
  94 <paramdef>lwres_buffer_t *b</paramdef>
  95 <paramdef>unsigned int n</paramdef>
  96 </funcprototype>
  97
  98 <funcprototype>
  99 <funcdef>
 100 void
 101 <function>lwres_buffer_subtract</function></funcdef>
 102 <paramdef>lwres_buffer_t *b</paramdef>
 103 <paramdef>unsigned int n</paramdef>
 104 </funcprototype>
 105
 106 <funcprototype>
 107 <funcdef>
 108 void
 109 <function>lwres_buffer_clear</function></funcdef>
 110 <paramdef>lwres_buffer_t *b</paramdef>
 111 </funcprototype>
 112
 113 <funcprototype>
 114 <funcdef>
 115 void
 116 <function>lwres_buffer_first</function></funcdef>
 117 <paramdef>lwres_buffer_t *b</paramdef>
 118 </funcprototype>
 119
 120 <funcprototype>
 121 <funcdef>
 122 void
 123 <function>lwres_buffer_forward</function></funcdef>
 124 <paramdef>lwres_buffer_t *b</paramdef>
 125 <paramdef>unsigned int n</paramdef>
 126 </funcprototype>
 127 <funcprototype>
 128
 129 <funcdef>
 130 void
 131 <function>lwres_buffer_back</function></funcdef>
 132 <paramdef>lwres_buffer_t *b</paramdef>
 133 <paramdef>unsigned int n</paramdef>
 134 </funcprototype>
 135
 136 <funcprototype>
 137 <funcdef>
 138 lwres_uint8_t
 139 <function>lwres_buffer_getuint8</function></funcdef>
 140 <paramdef>lwres_buffer_t *b</paramdef>
 141 </funcprototype>
 142
 143 <funcprototype>
 144 <funcdef>
 145 void
 146 <function>lwres_buffer_putuint8</function></funcdef>
 147 <paramdef>lwres_buffer_t *b</paramdef>
 148 <paramdef>lwres_uint8_t val</paramdef>
 149 </funcprototype>
 150
 151 <funcprototype>
 152 <funcdef>
 153 lwres_uint16_t
 154 <function>lwres_buffer_getuint16</function></funcdef>
 155 <paramdef>lwres_buffer_t *b</paramdef>
 156 </funcprototype>
 157
 158 <funcprototype>
 159 <funcdef>
 160 void
 161 <function>lwres_buffer_putuint16</function></funcdef>
 162 <paramdef>lwres_buffer_t *b</paramdef>
 163 <paramdef>lwres_uint16_t val</paramdef>
 164 </funcprototype>
 165
 166 <funcprototype>
 167 <funcdef>
 168 lwres_uint32_t
 169 <function>lwres_buffer_getuint32</function></funcdef>
 170 <paramdef>lwres_buffer_t *b</paramdef>
 171 </funcprototype>
 172
 173 <funcprototype>
 174 <funcdef>
 175 void
 176 <function>lwres_buffer_putuint32</function></funcdef>
 177 <paramdef>lwres_buffer_t *b</paramdef>
 178 <paramdef>lwres_uint32_t val</paramdef>
 179 </funcprototype>
 180
 181 <funcprototype>
 182 <funcdef>
 183 void
 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>
 188 </funcprototype>
 189
 190 <funcprototype>
 191 <funcdef>
 192 void
 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>
 197 </funcprototype>
 198
 199 </funcsynopsis>
 200 </refsynopsisdiv>
 201
 202 <refsect1>
 203
 204 <title>DESCRIPTION</title>
 205 <para>
 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.
 211 </para>
 212 <para>
 213 A buffer is a region of memory, together with a set of related
 214 subregions.
 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
 219 last used byte.
 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
 223 buffer commands.
 224 Initially, the used region is empty.
 225 </para>
 226 <para>
 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
 233 region.
 234 The size of the consumed region can be changed using various
 235 buffer commands.
 236 Initially, the consumed region is empty.
 237 </para>
 238 <para>
 239 The <emphasis>active region</emphasis> is an (optional) subregion of the remaining
 240 region.
 241 It extends from the current offset to an offset in the
 242 remaining region.
 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.
 246 </para>
 247 <para>
 248 <programlisting>
 249
 250    /------------entire length---------------\\
 251    /----- used region -----\\/-- available --\\
 252    +----------------------------------------+
 253    | consumed  | remaining |                |
 254    +----------------------------------------+
 255    a           b     c     d                e
 256
 257   a == base of buffer.
 258   b == current pointer.  Can be anywhere between a and d.
 259   c == active pointer.  Meaningful between b and d.
 260   d == used pointer.
 261   e == length of buffer.
 262
 263   a-e == entire length of buffer.
 264   a-d == used region.
 265   a-b == consumed region.
 266   b-d == remaining region.
 267   b-c == optional active region.
 268 </programlisting>
 269 </para>
 270 <para>
 271 <function>lwres_buffer_init()</function>
 272 initializes the
 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>
 279 </para>
 280 <para>
 281 <function>lwres_buffer_invalidate()</function>
 282 marks the buffer
 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.
 286 </para>
 287 <para>
 288 The functions
 289 <function>lwres_buffer_add()</function>
 290 and
 291 <function>lwres_buffer_subtract()</function>
 292 respectively increase and decrease the used space in
 293 buffer
 294 <parameter>*b</parameter>
 295 by
 296 <parameter>n</parameter>
 297 bytes.
 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>.
 305 </para>
 306 <para>
 307 A buffer is re-initialised by
 308 <function>lwres_buffer_clear()</function>.
 309 The function sets
 310 <structfield>used</structfield> ,
 311 <structfield>current</structfield>
 312 and
 313 <structfield>active</structfield>
 314 to zero.
 315 </para>
 316 <para>
 317 <function>lwres_buffer_first</function>
 318 makes the consumed region of buffer
 319 <parameter>*p</parameter>
 320 empty by setting
 321 <structfield>current</structfield>
 322 to zero (the start of the buffer).
 323 </para>
 324 <para>
 325 <function>lwres_buffer_forward()</function>
 326 increases the consumed region of buffer
 327 <parameter>*b</parameter>
 328 by
 329 <parameter>n</parameter>
 330 bytes, checking for overflow.
 331 Similarly,
 332 <function>lwres_buffer_back()</function>
 333 decreases buffer
 334 <parameter>b</parameter>'s
 335 consumed region by
 336 <parameter>n</parameter>
 337 bytes and checks for underflow.
 338 </para>
 339 <para>
 340 <function>lwres_buffer_getuint8()</function>
 341 reads an unsigned 8-bit integer from
 342 <parameter>*b</parameter>
 343 and returns it.
 344 <function>lwres_buffer_putuint8()</function>
 345 writes the unsigned 8-bit integer
 346 <parameter>val</parameter>
 347 to buffer
 348 <parameter>*b</parameter>.
 349 </para>
 350 <para>
 351 <function>lwres_buffer_getuint16()</function>
 352 and
 353 <function>lwres_buffer_getuint32()</function>
 354 are identical to
 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>.
 359 Similarly,
 360 <function>lwres_buffer_putuint16()</function>
 361 and
 362 <function>lwres_buffer_putuint32()</function>
 363 writes the unsigned 16-bit or 32-bit integer
 364 <parameter>val</parameter>
 365 to buffer
 366 <parameter>b</parameter>,
 367 in network byte order.
 368 </para>
 369 <para>
 370 Arbitrary amounts of data are read or written from a lightweight
 371 resolver buffer with
 372 <function>lwres_buffer_getmem()</function>
 373 and
 374 <function>lwres_buffer_putmem()</function>
 375 respectively.
 376 <function>lwres_buffer_putmem()</function>
 377 copies
 378 <parameter>length</parameter>
 379 bytes of memory at
 380 <parameter>base</parameter>
 381 to
 382 <parameter>b</parameter>.
 383 Conversely,
 384 <function>lwres_buffer_getmem()</function>
 385 copies
 386 <parameter>length</parameter>
 387 bytes of memory from
 388 <parameter>b</parameter>
 389 to
 390 <parameter>base</parameter>.
 391 </para>
 392 </refsect1>
 393 </refentry>