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

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2004, 2005, 2007  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000, 2001  Internet Software Consortium.
   7  -
   8  - Permission to use, copy, modify, and/or 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.6 2007/08/28 07:19:18 tbox 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       <year>2007</year>
  39       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  40     </copyright>
  41     <copyright>
  42       <year>2000</year>
  43       <year>2001</year>
  44       <holder>Internet Software Consortium.</holder>
  45     </copyright>
  46   </docinfo>
  47
  48 <refnamediv>
  49 <refname>lwres_buffer_init</refname>
  50 <refname>lwres_buffer_invalidate</refname>
  51 <refname>lwres_buffer_add</refname>
  52 <refname>lwres_buffer_subtract</refname>
  53 <refname>lwres_buffer_clear</refname>
  54 <refname>lwres_buffer_first</refname>
  55 <refname>lwres_buffer_forward</refname>
  56 <refname>lwres_buffer_back</refname>
  57 <refname>lwres_buffer_getuint8</refname>
  58 <refname>lwres_buffer_putuint8</refname>
  59 <refname>lwres_buffer_getuint16</refname>
  60 <refname>lwres_buffer_putuint16</refname>
  61 <refname>lwres_buffer_getuint32</refname>
  62 <refname>lwres_buffer_putuint32</refname>
  63 <refname>lwres_buffer_putmem</refname>
  64 <refname>lwres_buffer_getmem</refname>
  65 <refpurpose>lightweight resolver buffer management</refpurpose>
  66 </refnamediv>
  67
  68 <refsynopsisdiv>
  69
  70 <funcsynopsis>
  71 <funcsynopsisinfo>
  72 #include &lt;lwres/lwbuffer.h&gt;
  73 </funcsynopsisinfo>
  74
  75 <funcprototype>
  76
  77 <funcdef>
  78 void
  79 <function>lwres_buffer_init</function></funcdef>
  80 <paramdef>lwres_buffer_t *b</paramdef>
  81 <paramdef>void *base</paramdef>
  82 <paramdef>unsigned int length</paramdef>
  83 </funcprototype>
  84
  85 <funcprototype>
  86 <funcdef>
  87 void
  88 <function>lwres_buffer_invalidate</function></funcdef>
  89 <paramdef>lwres_buffer_t *b</paramdef>
  90 </funcprototype>
  91 <funcprototype>
  92 <funcdef>
  93 void
  94 <function>lwres_buffer_add</function></funcdef>
  95 <paramdef>lwres_buffer_t *b</paramdef>
  96 <paramdef>unsigned int n</paramdef>
  97 </funcprototype>
  98
  99 <funcprototype>
 100 <funcdef>
 101 void
 102 <function>lwres_buffer_subtract</function></funcdef>
 103 <paramdef>lwres_buffer_t *b</paramdef>
 104 <paramdef>unsigned int n</paramdef>
 105 </funcprototype>
 106
 107 <funcprototype>
 108 <funcdef>
 109 void
 110 <function>lwres_buffer_clear</function></funcdef>
 111 <paramdef>lwres_buffer_t *b</paramdef>
 112 </funcprototype>
 113
 114 <funcprototype>
 115 <funcdef>
 116 void
 117 <function>lwres_buffer_first</function></funcdef>
 118 <paramdef>lwres_buffer_t *b</paramdef>
 119 </funcprototype>
 120
 121 <funcprototype>
 122 <funcdef>
 123 void
 124 <function>lwres_buffer_forward</function></funcdef>
 125 <paramdef>lwres_buffer_t *b</paramdef>
 126 <paramdef>unsigned int n</paramdef>
 127 </funcprototype>
 128 <funcprototype>
 129
 130 <funcdef>
 131 void
 132 <function>lwres_buffer_back</function></funcdef>
 133 <paramdef>lwres_buffer_t *b</paramdef>
 134 <paramdef>unsigned int n</paramdef>
 135 </funcprototype>
 136
 137 <funcprototype>
 138 <funcdef>
 139 lwres_uint8_t
 140 <function>lwres_buffer_getuint8</function></funcdef>
 141 <paramdef>lwres_buffer_t *b</paramdef>
 142 </funcprototype>
 143
 144 <funcprototype>
 145 <funcdef>
 146 void
 147 <function>lwres_buffer_putuint8</function></funcdef>
 148 <paramdef>lwres_buffer_t *b</paramdef>
 149 <paramdef>lwres_uint8_t val</paramdef>
 150 </funcprototype>
 151
 152 <funcprototype>
 153 <funcdef>
 154 lwres_uint16_t
 155 <function>lwres_buffer_getuint16</function></funcdef>
 156 <paramdef>lwres_buffer_t *b</paramdef>
 157 </funcprototype>
 158
 159 <funcprototype>
 160 <funcdef>
 161 void
 162 <function>lwres_buffer_putuint16</function></funcdef>
 163 <paramdef>lwres_buffer_t *b</paramdef>
 164 <paramdef>lwres_uint16_t val</paramdef>
 165 </funcprototype>
 166
 167 <funcprototype>
 168 <funcdef>
 169 lwres_uint32_t
 170 <function>lwres_buffer_getuint32</function></funcdef>
 171 <paramdef>lwres_buffer_t *b</paramdef>
 172 </funcprototype>
 173
 174 <funcprototype>
 175 <funcdef>
 176 void
 177 <function>lwres_buffer_putuint32</function></funcdef>
 178 <paramdef>lwres_buffer_t *b</paramdef>
 179 <paramdef>lwres_uint32_t val</paramdef>
 180 </funcprototype>
 181
 182 <funcprototype>
 183 <funcdef>
 184 void
 185 <function>lwres_buffer_putmem</function></funcdef>
 186 <paramdef>lwres_buffer_t *b</paramdef>
 187 <paramdef>const unsigned char *base</paramdef>
 188 <paramdef>unsigned int length</paramdef>
 189 </funcprototype>
 190
 191 <funcprototype>
 192 <funcdef>
 193 void
 194 <function>lwres_buffer_getmem</function></funcdef>
 195 <paramdef>lwres_buffer_t *b</paramdef>
 196 <paramdef>unsigned char *base</paramdef>
 197 <paramdef>unsigned int length</paramdef>
 198 </funcprototype>
 199
 200 </funcsynopsis>
 201 </refsynopsisdiv>
 202
 203 <refsect1>
 204
 205 <title>DESCRIPTION</title>
 206 <para>
 207 These functions provide bounds checked access to a region of memory
 208 where data is being read or written.
 209 They are based on, and similar to, the
 210 <literal>isc_buffer_</literal>
 211 functions in the ISC library.
 212 </para>
 213 <para>
 214 A buffer is a region of memory, together with a set of related
 215 subregions.
 216 The <emphasis>used region</emphasis> and the
 217 <emphasis>available</emphasis> region are disjoint, and
 218 their union is the buffer's region.
 219 The used region extends from the beginning of the buffer region to the
 220 last used byte.
 221 The available region extends from one byte greater than the last used
 222 byte to the end of the  buffer's region.
 223 The size of the used region can be changed using various
 224 buffer commands.
 225 Initially, the used region is empty.
 226 </para>
 227 <para>
 228 The used region is further subdivided into two disjoint regions: the
 229 <emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
 230 The union of these two regions is the used region.
 231 The consumed region extends from the beginning of the used region to
 232 the byte before the <emphasis>current</emphasis> offset (if any).
 233 The <emphasis>remaining</emphasis> region the current pointer to the end of the used
 234 region.
 235 The size of the consumed region can be changed using various
 236 buffer commands.
 237 Initially, the consumed region is empty.
 238 </para>
 239 <para>
 240 The <emphasis>active region</emphasis> is an (optional) subregion of the remaining
 241 region.
 242 It extends from the current offset to an offset in the
 243 remaining region.
 244 Initially, the active region is empty.
 245 If the current offset advances beyond the chosen offset,
 246 the active region will also be empty.
 247 </para>
 248 <para>
 249 <programlisting>
 250
 251    /------------entire length---------------\\
 252    /----- used region -----\\/-- available --\\
 253    +----------------------------------------+
 254    | consumed  | remaining |                |
 255    +----------------------------------------+
 256    a           b     c     d                e
 257
 258   a == base of buffer.
 259   b == current pointer.  Can be anywhere between a and d.
 260   c == active pointer.  Meaningful between b and d.
 261   d == used pointer.
 262   e == length of buffer.
 263
 264   a-e == entire length of buffer.
 265   a-d == used region.
 266   a-b == consumed region.
 267   b-d == remaining region.
 268   b-c == optional active region.
 269 </programlisting>
 270 </para>
 271 <para>
 272 <function>lwres_buffer_init()</function>
 273 initializes the
 274 <type>lwres_buffer_t</type>
 275 <parameter>*b</parameter>
 276 and assocates it with the memory region of size
 277 <parameter>length</parameter>
 278 bytes starting at location
 279 <parameter>base.</parameter>
 280 </para>
 281 <para>
 282 <function>lwres_buffer_invalidate()</function>
 283 marks the buffer
 284 <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.
 287 </para>
 288 <para>
 289 The functions
 290 <function>lwres_buffer_add()</function>
 291 and
 292 <function>lwres_buffer_subtract()</function>
 293 respectively increase and decrease the used space in
 294 buffer
 295 <parameter>*b</parameter>
 296 by
 297 <parameter>n</parameter>
 298 bytes.
 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>.
 306 </para>
 307 <para>
 308 A buffer is re-initialised by
 309 <function>lwres_buffer_clear()</function>.
 310 The function sets
 311 <structfield>used</structfield> ,
 312 <structfield>current</structfield>
 313 and
 314 <structfield>active</structfield>
 315 to zero.
 316 </para>
 317 <para>
 318 <function>lwres_buffer_first</function>
 319 makes the consumed region of buffer
 320 <parameter>*p</parameter>
 321 empty by setting
 322 <structfield>current</structfield>
 323 to zero (the start of the buffer).
 324 </para>
 325 <para>
 326 <function>lwres_buffer_forward()</function>
 327 increases the consumed region of buffer
 328 <parameter>*b</parameter>
 329 by
 330 <parameter>n</parameter>
 331 bytes, checking for overflow.
 332 Similarly,
 333 <function>lwres_buffer_back()</function>
 334 decreases buffer
 335 <parameter>b</parameter>'s
 336 consumed region by
 337 <parameter>n</parameter>
 338 bytes and checks for underflow.
 339 </para>
 340 <para>
 341 <function>lwres_buffer_getuint8()</function>
 342 reads an unsigned 8-bit integer from
 343 <parameter>*b</parameter>
 344 and returns it.
 345 <function>lwres_buffer_putuint8()</function>
 346 writes the unsigned 8-bit integer
 347 <parameter>val</parameter>
 348 to buffer
 349 <parameter>*b</parameter>.
 350 </para>
 351 <para>
 352 <function>lwres_buffer_getuint16()</function>
 353 and
 354 <function>lwres_buffer_getuint32()</function>
 355 are identical to
 356 <function>lwres_buffer_putuint8()</function>
 357 except that they respectively read an unsigned 16-bit or 32-bit integer
 358 in network byte order from
 359 <parameter>b</parameter>.
 360 Similarly,
 361 <function>lwres_buffer_putuint16()</function>
 362 and
 363 <function>lwres_buffer_putuint32()</function>
 364 writes the unsigned 16-bit or 32-bit integer
 365 <parameter>val</parameter>
 366 to buffer
 367 <parameter>b</parameter>,
 368 in network byte order.
 369 </para>
 370 <para>
 371 Arbitrary amounts of data are read or written from a lightweight
 372 resolver buffer with
 373 <function>lwres_buffer_getmem()</function>
 374 and
 375 <function>lwres_buffer_putmem()</function>
 376 respectively.
 377 <function>lwres_buffer_putmem()</function>
 378 copies
 379 <parameter>length</parameter>
 380 bytes of memory at
 381 <parameter>base</parameter>
 382 to
 383 <parameter>b</parameter>.
 384 Conversely,
 385 <function>lwres_buffer_getmem()</function>
 386 copies
 387 <parameter>length</parameter>
 388 bytes of memory from
 389 <parameter>b</parameter>
 390 to
 391 <parameter>base</parameter>.
 392 </para>
 393 </refsect1>
 394 </refentry>