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 — 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 <lwres/lwbuffer.h> 35</pre> 36<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 37<tr> 38<td><code class="funcdef"> 39void 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"> 60void 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"> 69void 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"> 85void 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"> 100void 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"> 108void 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"> 117void 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"> 133void 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"> 148lwres_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"> 157void 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"> 172lwres_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"> 181void 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"> 196lwres_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"> 205void 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"> 221void 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"> 243void 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> 456