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

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2000, 2001 Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and/or 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 ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17 <html>
  18 <head>
  19 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  20 <title>lwres_buffer</title>
  21 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
  22 </head>
  23 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
  24 <a name="id-1"></a><div class="titlepage"></div>
  25 <div class="refnamediv">
  26 <h2>Name</h2>
  27 <p>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 &#8212; lightweight resolver buffer management</p>
  28 </div>
  29 <div class="refsynopsisdiv">
  30 <h2>Synopsis</h2>
  31 <div class="funcsynopsis">
  32 <pre class="funcsynopsisinfo">
  33 #include &lt;lwres/lwbuffer.h&gt;
  34 </pre>
  35 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  36 <tr>
  37 <td><code class="funcdef">
  38 void
  39 <b class="fsfunc">lwres_buffer_init</b>(</code></td>
  40 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
  41 </tr>
  42 <tr>
  43 <td> </td>
  44 <td>void *<var class="pdparam">base</var>, </td>
  45 </tr>
  46 <tr>
  47 <td> </td>
  48 <td>unsigned int <var class="pdparam">length</var><code>)</code>;</td>
  49 </tr>
  50 </table>
  51 <div class="funcprototype-spacer"> </div>
  52 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
  53 <td><code class="funcdef">
  54 void
  55 <b class="fsfunc">lwres_buffer_invalidate</b>(</code></td>
  56 <td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
  57 </tr></table>
  58 <div class="funcprototype-spacer"> </div>
  59 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  60 <tr>
  61 <td><code class="funcdef">
  62 void
  63 <b class="fsfunc">lwres_buffer_add</b>(</code></td>
  64 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
  65 </tr>
  66 <tr>
  67 <td> </td>
  68 <td>unsigned int <var class="pdparam">n</var><code>)</code>;</td>
  69 </tr>
  70 </table>
  71 <div class="funcprototype-spacer"> </div>
  72 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  73 <tr>
  74 <td><code class="funcdef">
  75 void
  76 <b class="fsfunc">lwres_buffer_subtract</b>(</code></td>
  77 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
  78 </tr>
  79 <tr>
  80 <td> </td>
  81 <td>unsigned int <var class="pdparam">n</var><code>)</code>;</td>
  82 </tr>
  83 </table>
  84 <div class="funcprototype-spacer"> </div>
  85 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
  86 <td><code class="funcdef">
  87 void
  88 <b class="fsfunc">lwres_buffer_clear</b>(</code></td>
  89 <td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
  90 </tr></table>
  91 <div class="funcprototype-spacer"> </div>
  92 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
  93 <td><code class="funcdef">
  94 void
  95 <b class="fsfunc">lwres_buffer_first</b>(</code></td>
  96 <td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
  97 </tr></table>
  98 <div class="funcprototype-spacer"> </div>
  99 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 100 <tr>
 101 <td><code class="funcdef">
 102 void
 103 <b class="fsfunc">lwres_buffer_forward</b>(</code></td>
 104 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
 105 </tr>
 106 <tr>
 107 <td> </td>
 108 <td>unsigned int <var class="pdparam">n</var><code>)</code>;</td>
 109 </tr>
 110 </table>
 111 <div class="funcprototype-spacer"> </div>
 112 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 113 <tr>
 114 <td><code class="funcdef">
 115 void
 116 <b class="fsfunc">lwres_buffer_back</b>(</code></td>
 117 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
 118 </tr>
 119 <tr>
 120 <td> </td>
 121 <td>unsigned int <var class="pdparam">n</var><code>)</code>;</td>
 122 </tr>
 123 </table>
 124 <div class="funcprototype-spacer"> </div>
 125 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
 126 <td><code class="funcdef">
 127 lwres_uint8_t
 128 <b class="fsfunc">lwres_buffer_getuint8</b>(</code></td>
 129 <td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
 130 </tr></table>
 131 <div class="funcprototype-spacer"> </div>
 132 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 133 <tr>
 134 <td><code class="funcdef">
 135 void
 136 <b class="fsfunc">lwres_buffer_putuint8</b>(</code></td>
 137 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
 138 </tr>
 139 <tr>
 140 <td> </td>
 141 <td>lwres_uint8_t <var class="pdparam">val</var><code>)</code>;</td>
 142 </tr>
 143 </table>
 144 <div class="funcprototype-spacer"> </div>
 145 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
 146 <td><code class="funcdef">
 147 lwres_uint16_t
 148 <b class="fsfunc">lwres_buffer_getuint16</b>(</code></td>
 149 <td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
 150 </tr></table>
 151 <div class="funcprototype-spacer"> </div>
 152 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 153 <tr>
 154 <td><code class="funcdef">
 155 void
 156 <b class="fsfunc">lwres_buffer_putuint16</b>(</code></td>
 157 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
 158 </tr>
 159 <tr>
 160 <td> </td>
 161 <td>lwres_uint16_t <var class="pdparam">val</var><code>)</code>;</td>
 162 </tr>
 163 </table>
 164 <div class="funcprototype-spacer"> </div>
 165 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
 166 <td><code class="funcdef">
 167 lwres_uint32_t
 168 <b class="fsfunc">lwres_buffer_getuint32</b>(</code></td>
 169 <td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
 170 </tr></table>
 171 <div class="funcprototype-spacer"> </div>
 172 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 173 <tr>
 174 <td><code class="funcdef">
 175 void
 176 <b class="fsfunc">lwres_buffer_putuint32</b>(</code></td>
 177 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
 178 </tr>
 179 <tr>
 180 <td> </td>
 181 <td>lwres_uint32_t <var class="pdparam">val</var><code>)</code>;</td>
 182 </tr>
 183 </table>
 184 <div class="funcprototype-spacer"> </div>
 185 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 186 <tr>
 187 <td><code class="funcdef">
 188 void
 189 <b class="fsfunc">lwres_buffer_putmem</b>(</code></td>
 190 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
 191 </tr>
 192 <tr>
 193 <td> </td>
 194 <td>const unsigned char *<var class="pdparam">base</var>, </td>
 195 </tr>
 196 <tr>
 197 <td> </td>
 198 <td>unsigned int <var class="pdparam">length</var><code>)</code>;</td>
 199 </tr>
 200 </table>
 201 <div class="funcprototype-spacer"> </div>
 202 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 203 <tr>
 204 <td><code class="funcdef">
 205 void
 206 <b class="fsfunc">lwres_buffer_getmem</b>(</code></td>
 207 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
 208 </tr>
 209 <tr>
 210 <td> </td>
 211 <td>unsigned char *<var class="pdparam">base</var>, </td>
 212 </tr>
 213 <tr>
 214 <td> </td>
 215 <td>unsigned int <var class="pdparam">length</var><code>)</code>;</td>
 216 </tr>
 217 </table>
 218 <div class="funcprototype-spacer"> </div>
 219 </div>
 220 </div>
 221 <div class="refsection">
 222 <a name="id-1.7"></a><h2>DESCRIPTION</h2>
 223 <p>
 224       These functions provide bounds checked access to a region of memory
 225       where data is being read or written.
 226       They are based on, and similar to, the
 227       <code class="literal">isc_buffer_</code>
 228       functions in the ISC library.
 229     </p>
 230 <p>
 231       A buffer is a region of memory, together with a set of related
 232       subregions.
 233       The <span class="emphasis"><em>used region</em></span> and the
 234       <span class="emphasis"><em>available</em></span> region are disjoint, and
 235       their union is the buffer's region.
 236       The used region extends from the beginning of the buffer region to the
 237       last used byte.
 238       The available region extends from one byte greater than the last used
 239       byte to the end of the  buffer's region.
 240       The size of the used region can be changed using various
 241       buffer commands.
 242       Initially, the used region is empty.
 243     </p>
 244 <p>
 245       The used region is further subdivided into two disjoint regions: the
 246       <span class="emphasis"><em>consumed region</em></span> and the <span class="emphasis"><em>remaining region</em></span>.
 247       The union of these two regions is the used region.
 248       The consumed region extends from the beginning of the used region to
 249       the byte before the <span class="emphasis"><em>current</em></span> offset (if any).
 250       The <span class="emphasis"><em>remaining</em></span> region the current pointer to the end
 251       of the used
 252       region.
 253       The size of the consumed region can be changed using various
 254       buffer commands.
 255       Initially, the consumed region is empty.
 256     </p>
 257 <p>
 258       The <span class="emphasis"><em>active region</em></span> is an (optional) subregion of the
 259       remaining
 260       region.
 261       It extends from the current offset to an offset in the
 262       remaining region.
 263       Initially, the active region is empty.
 264       If the current offset advances beyond the chosen offset,
 265       the active region will also be empty.
 266     </p>
 267 <pre class="programlisting">
 268    /------------entire length---------------\\
 269    /----- used region -----\\/-- available --\\
 270    +----------------------------------------+
 271    | consumed  | remaining |                |
 272    +----------------------------------------+
 273    a           b     c     d                e
 274       </pre>
 275 <p>
 276     </p>
 277 <pre class="programlisting">
 278   a == base of buffer.
 279   b == current pointer.  Can be anywhere between a and d.
 280   c == active pointer.  Meaningful between b and d.
 281   d == used pointer.
 282   e == length of buffer.
 283       </pre>
 284 <p>
 285     </p>
 286 <pre class="programlisting">
 287   a-e == entire length of buffer.
 288   a-d == used region.
 289   a-b == consumed region.
 290   b-d == remaining region.
 291   b-c == optional active region.
 292 </pre>
 293 <p>
 294     </p>
 295 <p><code class="function">lwres_buffer_init()</code>
 296       initializes the
 297       <span class="type">lwres_buffer_t</span>
 298       <em class="parameter"><code>*b</code></em>
 299       and assocates it with the memory region of size
 300       <em class="parameter"><code>length</code></em>
 301       bytes starting at location
 302       <em class="parameter"><code>base.</code></em>
 303     </p>
 304 <p><code class="function">lwres_buffer_invalidate()</code>
 305       marks the buffer <em class="parameter"><code>*b</code></em>
 306       as invalid.  Invalidating a buffer after use is not required,
 307       but makes it possible to catch its possible accidental use.
 308     </p>
 309 <p>
 310       The functions
 311       <code class="function">lwres_buffer_add()</code>
 312       and
 313       <code class="function">lwres_buffer_subtract()</code>
 314       respectively increase and decrease the used space in
 315       buffer
 316       <em class="parameter"><code>*b</code></em>
 317       by
 318       <em class="parameter"><code>n</code></em>
 319       bytes.
 320       <code class="function">lwres_buffer_add()</code>
 321       checks for buffer overflow and
 322       <code class="function">lwres_buffer_subtract()</code>
 323       checks for underflow.
 324       These functions do not allocate or deallocate memory.
 325       They just change the value of
 326       <code class="varname">used</code>.
 327     </p>
 328 <p>
 329       A buffer is re-initialised by
 330       <code class="function">lwres_buffer_clear()</code>.
 331       The function sets
 332       <code class="varname">used</code>,
 333       <code class="varname">current</code>
 334       and
 335       <code class="varname">active</code>
 336       to zero.
 337     </p>
 338 <p><code class="function">lwres_buffer_first</code>
 339       makes the consumed region of buffer
 340       <em class="parameter"><code>*p</code></em>
 341       empty by setting
 342       <code class="varname">current</code>
 343       to zero (the start of the buffer).
 344     </p>
 345 <p><code class="function">lwres_buffer_forward()</code>
 346       increases the consumed region of buffer
 347       <em class="parameter"><code>*b</code></em>
 348       by
 349       <em class="parameter"><code>n</code></em>
 350       bytes, checking for overflow.
 351       Similarly,
 352       <code class="function">lwres_buffer_back()</code>
 353       decreases buffer
 354       <em class="parameter"><code>b</code></em>'s
 355       consumed region by
 356       <em class="parameter"><code>n</code></em>
 357       bytes and checks for underflow.
 358     </p>
 359 <p><code class="function">lwres_buffer_getuint8()</code>
 360       reads an unsigned 8-bit integer from
 361       <em class="parameter"><code>*b</code></em>
 362       and returns it.
 363       <code class="function">lwres_buffer_putuint8()</code>
 364       writes the unsigned 8-bit integer
 365       <em class="parameter"><code>val</code></em>
 366       to buffer
 367       <em class="parameter"><code>*b</code></em>.
 368     </p>
 369 <p><code class="function">lwres_buffer_getuint16()</code>
 370       and
 371       <code class="function">lwres_buffer_getuint32()</code>
 372       are identical to
 373       <code class="function">lwres_buffer_putuint8()</code>
 374       except that they respectively read an unsigned 16-bit or 32-bit integer
 375       in network byte order from
 376       <em class="parameter"><code>b</code></em>.
 377       Similarly,
 378       <code class="function">lwres_buffer_putuint16()</code>
 379       and
 380       <code class="function">lwres_buffer_putuint32()</code>
 381       writes the unsigned 16-bit or 32-bit integer
 382       <em class="parameter"><code>val</code></em>
 383       to buffer
 384       <em class="parameter"><code>b</code></em>,
 385       in network byte order.
 386     </p>
 387 <p>
 388       Arbitrary amounts of data are read or written from a lightweight
 389       resolver buffer with
 390       <code class="function">lwres_buffer_getmem()</code>
 391       and
 392       <code class="function">lwres_buffer_putmem()</code>
 393       respectively.
 394       <code class="function">lwres_buffer_putmem()</code>
 395       copies
 396       <em class="parameter"><code>length</code></em>
 397       bytes of memory at
 398       <em class="parameter"><code>base</code></em>
 399       to
 400       <em class="parameter"><code>b</code></em>.
 401       Conversely,
 402       <code class="function">lwres_buffer_getmem()</code>
 403       copies
 404       <em class="parameter"><code>length</code></em>
 405       bytes of memory from
 406       <em class="parameter"><code>b</code></em>
 407       to
 408       <em class="parameter"><code>base</code></em>.
 409     </p>
 410 </div>
 411 </div></body>
 412 </html>