external/bsd/bind/dist/lib/lwres/man/lwres_buffer.html

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