contrib/bind-9.2.4rc7/lib/lwres/man/lwres_buffer.html

   1 <!--
   2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2001  Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and 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
  18 <!-- $Id: lwres_buffer.html,v 1.4.2.2 2004/03/15 04:45:00 marka Exp $ -->
  19
  20 <HTML
  21 ><HEAD
  22 ><TITLE
  23 >lwres_buffer</TITLE
  24 ><META
  25 NAME="GENERATOR"
  26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
  27 "></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 BGCOLOR="#FFFFFF"
  31 TEXT="#000000"
  32 LINK="#0000FF"
  33 VLINK="#840084"
  34 ALINK="#0000FF"
  35 ><H1
  36 ><A
  37 NAME="AEN1"
  38 >lwres_buffer</A
  39 ></H1
  40 ><DIV
  41 CLASS="REFNAMEDIV"
  42 ><A
  43 NAME="AEN8"
  44 ></A
  45 ><H2
  46 >Name</H2
  47 >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&nbsp;--&nbsp;lightweight resolver buffer management</DIV
  48 ><DIV
  49 CLASS="REFSYNOPSISDIV"
  50 ><A
  51 NAME="AEN26"
  52 ></A
  53 ><H2
  54 >Synopsis</H2
  55 ><DIV
  56 CLASS="FUNCSYNOPSIS"
  57 ><A
  58 NAME="AEN27"
  59 ></A
  60 ><P
  61 ></P
  62 ><PRE
  63 CLASS="FUNCSYNOPSISINFO"
  64 >#include &lt;lwres/lwbuffer.h&gt;</PRE
  65 ><P
  66 ><CODE
  67 ><CODE
  68 CLASS="FUNCDEF"
  69 >void
  70 lwres_buffer_init</CODE
  71 >(lwres_buffer_t *b, void *base, unsigned int length);</CODE
  72 ></P
  73 ><P
  74 ><CODE
  75 ><CODE
  76 CLASS="FUNCDEF"
  77 >void
  78 lwres_buffer_invalidate</CODE
  79 >(lwres_buffer_t *b);</CODE
  80 ></P
  81 ><P
  82 ><CODE
  83 ><CODE
  84 CLASS="FUNCDEF"
  85 >void
  86 lwres_buffer_add</CODE
  87 >(lwres_buffer_t *b, unsigned int n);</CODE
  88 ></P
  89 ><P
  90 ><CODE
  91 ><CODE
  92 CLASS="FUNCDEF"
  93 >void
  94 lwres_buffer_subtract</CODE
  95 >(lwres_buffer_t *b, unsigned int n);</CODE
  96 ></P
  97 ><P
  98 ><CODE
  99 ><CODE
 100 CLASS="FUNCDEF"
 101 >void
 102 lwres_buffer_clear</CODE
 103 >(lwres_buffer_t *b);</CODE
 104 ></P
 105 ><P
 106 ><CODE
 107 ><CODE
 108 CLASS="FUNCDEF"
 109 >void
 110 lwres_buffer_first</CODE
 111 >(lwres_buffer_t *b);</CODE
 112 ></P
 113 ><P
 114 ><CODE
 115 ><CODE
 116 CLASS="FUNCDEF"
 117 >void
 118 lwres_buffer_forward</CODE
 119 >(lwres_buffer_t *b, unsigned int n);</CODE
 120 ></P
 121 ><P
 122 ><CODE
 123 ><CODE
 124 CLASS="FUNCDEF"
 125 >void
 126 lwres_buffer_back</CODE
 127 >(lwres_buffer_t *b, unsigned int n);</CODE
 128 ></P
 129 ><P
 130 ><CODE
 131 ><CODE
 132 CLASS="FUNCDEF"
 133 >lwres_uint8_t
 134 lwres_buffer_getuint8</CODE
 135 >(lwres_buffer_t *b);</CODE
 136 ></P
 137 ><P
 138 ><CODE
 139 ><CODE
 140 CLASS="FUNCDEF"
 141 >void
 142 lwres_buffer_putuint8</CODE
 143 >(lwres_buffer_t *b, lwres_uint8_t val);</CODE
 144 ></P
 145 ><P
 146 ><CODE
 147 ><CODE
 148 CLASS="FUNCDEF"
 149 >lwres_uint16_t
 150 lwres_buffer_getuint16</CODE
 151 >(lwres_buffer_t *b);</CODE
 152 ></P
 153 ><P
 154 ><CODE
 155 ><CODE
 156 CLASS="FUNCDEF"
 157 >void
 158 lwres_buffer_putuint16</CODE
 159 >(lwres_buffer_t *b, lwres_uint16_t val);</CODE
 160 ></P
 161 ><P
 162 ><CODE
 163 ><CODE
 164 CLASS="FUNCDEF"
 165 >lwres_uint32_t
 166 lwres_buffer_getuint32</CODE
 167 >(lwres_buffer_t *b);</CODE
 168 ></P
 169 ><P
 170 ><CODE
 171 ><CODE
 172 CLASS="FUNCDEF"
 173 >void
 174 lwres_buffer_putuint32</CODE
 175 >(lwres_buffer_t *b, lwres_uint32_t val);</CODE
 176 ></P
 177 ><P
 178 ><CODE
 179 ><CODE
 180 CLASS="FUNCDEF"
 181 >void
 182 lwres_buffer_putmem</CODE
 183 >(lwres_buffer_t *b, const unsigned char *base, unsigned int length);</CODE
 184 ></P
 185 ><P
 186 ><CODE
 187 ><CODE
 188 CLASS="FUNCDEF"
 189 >void
 190 lwres_buffer_getmem</CODE
 191 >(lwres_buffer_t *b, unsigned char *base, unsigned int length);</CODE
 192 ></P
 193 ><P
 194 ></P
 195 ></DIV
 196 ></DIV
 197 ><DIV
 198 CLASS="REFSECT1"
 199 ><A
 200 NAME="AEN106"
 201 ></A
 202 ><H2
 203 >DESCRIPTION</H2
 204 ><P
 205 >These functions provide bounds checked access to a region of memory
 206 where data is being read or written.
 207 They are based on, and similar to, the
 208 <TT
 209 CLASS="LITERAL"
 210 >isc_buffer_</TT
 211 >
 212 functions in the ISC library.</P
 213 ><P
 214 >A buffer is a region of memory, together with a set of related
 215 subregions.
 216 The <SPAN
 217 CLASS="emphasis"
 218 ><I
 219 CLASS="EMPHASIS"
 220 >used region</I
 221 ></SPAN
 222 > and the
 223 <SPAN
 224 CLASS="emphasis"
 225 ><I
 226 CLASS="EMPHASIS"
 227 >available</I
 228 ></SPAN
 229 > region are disjoint, and
 230 their union is the buffer's region.
 231 The used region extends from the beginning of the buffer region to the
 232 last used byte.
 233 The available region extends from one byte greater than the last used
 234 byte to the end of the  buffer's region.
 235 The size of the used region can be changed using various
 236 buffer commands.
 237 Initially, the used region is empty.</P
 238 ><P
 239 >The used region is further subdivided into two disjoint regions: the
 240 <SPAN
 241 CLASS="emphasis"
 242 ><I
 243 CLASS="EMPHASIS"
 244 >consumed region</I
 245 ></SPAN
 246 > and the <SPAN
 247 CLASS="emphasis"
 248 ><I
 249 CLASS="EMPHASIS"
 250 >remaining region</I
 251 ></SPAN
 252 >.
 253 The union of these two regions is the used region.
 254 The consumed region extends from the beginning of the used region to
 255 the byte before the <SPAN
 256 CLASS="emphasis"
 257 ><I
 258 CLASS="EMPHASIS"
 259 >current</I
 260 ></SPAN
 261 > offset (if any).
 262 The <SPAN
 263 CLASS="emphasis"
 264 ><I
 265 CLASS="EMPHASIS"
 266 >remaining</I
 267 ></SPAN
 268 > region the current pointer to the end of the used
 269 region.
 270 The size of the consumed region can be changed using various
 271 buffer commands.
 272 Initially, the consumed region is empty.</P
 273 ><P
 274 >The <SPAN
 275 CLASS="emphasis"
 276 ><I
 277 CLASS="EMPHASIS"
 278 >active region</I
 279 ></SPAN
 280 > is an (optional) subregion of the remaining
 281 region.
 282 It extends from the current offset to an offset in the
 283 remaining region.
 284 Initially, the active region is empty.
 285 If the current offset advances beyond the chosen offset,
 286 the active region will also be empty.</P
 287 ><P
 288 ><PRE
 289 CLASS="PROGRAMLISTING"
 290 >
 291    /------------entire length---------------\\
 292    /----- used region -----\\/-- available --\\
 293    +----------------------------------------+
 294    | consumed  | remaining |                |
 295    +----------------------------------------+
 296    a           b     c     d                e
 297
 298   a == base of buffer.
 299   b == current pointer.  Can be anywhere between a and d.
 300   c == active pointer.  Meaningful between b and d.
 301   d == used pointer.
 302   e == length of buffer.
 303
 304   a-e == entire length of buffer.
 305   a-d == used region.
 306   a-b == consumed region.
 307   b-d == remaining region.
 308   b-c == optional active region.</PRE
 309 ></P
 310 ><P
 311 ><TT
 312 CLASS="FUNCTION"
 313 >lwres_buffer_init()</TT
 314 >
 315 initializes the
 316 <SPAN
 317 CLASS="TYPE"
 318 >lwres_buffer_t</SPAN
 319 >
 320 <TT
 321 CLASS="PARAMETER"
 322 ><I
 323 >*b</I
 324 ></TT
 325 >
 326 and assocates it with the memory region of size
 327 <TT
 328 CLASS="PARAMETER"
 329 ><I
 330 >length</I
 331 ></TT
 332 >
 333 bytes starting at location
 334 <TT
 335 CLASS="PARAMETER"
 336 ><I
 337 >base.</I
 338 ></TT
 339 ></P
 340 ><P
 341 ><TT
 342 CLASS="FUNCTION"
 343 >lwres_buffer_invalidate()</TT
 344 >
 345 marks the buffer
 346 <TT
 347 CLASS="PARAMETER"
 348 ><I
 349 >*b</I
 350 ></TT
 351 >
 352 as invalid.  Invalidating a buffer after use is not required,
 353 but makes it possible to catch its possible accidental use.</P
 354 ><P
 355 >The functions
 356 <TT
 357 CLASS="FUNCTION"
 358 >lwres_buffer_add()</TT
 359 >
 360 and
 361 <TT
 362 CLASS="FUNCTION"
 363 >lwres_buffer_subtract()</TT
 364 >
 365 respectively increase and decrease the used space in
 366 buffer
 367 <TT
 368 CLASS="PARAMETER"
 369 ><I
 370 >*b</I
 371 ></TT
 372 >
 373 by
 374 <TT
 375 CLASS="PARAMETER"
 376 ><I
 377 >n</I
 378 ></TT
 379 >
 380 bytes.
 381 <TT
 382 CLASS="FUNCTION"
 383 >lwres_buffer_add()</TT
 384 >
 385 checks for buffer overflow and
 386 <TT
 387 CLASS="FUNCTION"
 388 >lwres_buffer_subtract()</TT
 389 >
 390 checks for underflow.
 391 These functions do not allocate or deallocate memory.
 392 They just change the value of
 393 <TT
 394 CLASS="STRUCTFIELD"
 395 ><I
 396 >used</I
 397 ></TT
 398 >.</P
 399 ><P
 400 >A buffer is re-initialised by
 401 <TT
 402 CLASS="FUNCTION"
 403 >lwres_buffer_clear()</TT
 404 >.
 405 The function sets
 406 <TT
 407 CLASS="STRUCTFIELD"
 408 ><I
 409 >used</I
 410 ></TT
 411 > ,
 412 <TT
 413 CLASS="STRUCTFIELD"
 414 ><I
 415 >current</I
 416 ></TT
 417 >
 418 and
 419 <TT
 420 CLASS="STRUCTFIELD"
 421 ><I
 422 >active</I
 423 ></TT
 424 >
 425 to zero.</P
 426 ><P
 427 ><TT
 428 CLASS="FUNCTION"
 429 >lwres_buffer_first</TT
 430 >
 431 makes the consumed region of buffer
 432 <TT
 433 CLASS="PARAMETER"
 434 ><I
 435 >*p</I
 436 ></TT
 437 >
 438 empty by setting
 439 <TT
 440 CLASS="STRUCTFIELD"
 441 ><I
 442 >current</I
 443 ></TT
 444 >
 445 to zero (the start of the buffer).</P
 446 ><P
 447 ><TT
 448 CLASS="FUNCTION"
 449 >lwres_buffer_forward()</TT
 450 >
 451 increases the consumed region of buffer
 452 <TT
 453 CLASS="PARAMETER"
 454 ><I
 455 >*b</I
 456 ></TT
 457 >
 458 by
 459 <TT
 460 CLASS="PARAMETER"
 461 ><I
 462 >n</I
 463 ></TT
 464 >
 465 bytes, checking for overflow.
 466 Similarly,
 467 <TT
 468 CLASS="FUNCTION"
 469 >lwres_buffer_back()</TT
 470 >
 471 decreases buffer
 472 <TT
 473 CLASS="PARAMETER"
 474 ><I
 475 >b</I
 476 ></TT
 477 >'s
 478 consumed region by
 479 <TT
 480 CLASS="PARAMETER"
 481 ><I
 482 >n</I
 483 ></TT
 484 >
 485 bytes and checks for underflow.</P
 486 ><P
 487 ><TT
 488 CLASS="FUNCTION"
 489 >lwres_buffer_getuint8()</TT
 490 >
 491 reads an unsigned 8-bit integer from
 492 <TT
 493 CLASS="PARAMETER"
 494 ><I
 495 >*b</I
 496 ></TT
 497 >
 498 and returns it.
 499 <TT
 500 CLASS="FUNCTION"
 501 >lwres_buffer_putuint8()</TT
 502 >
 503 writes the unsigned 8-bit integer
 504 <TT
 505 CLASS="PARAMETER"
 506 ><I
 507 >val</I
 508 ></TT
 509 >
 510 to buffer
 511 <TT
 512 CLASS="PARAMETER"
 513 ><I
 514 >*b</I
 515 ></TT
 516 >.</P
 517 ><P
 518 ><TT
 519 CLASS="FUNCTION"
 520 >lwres_buffer_getuint16()</TT
 521 >
 522 and
 523 <TT
 524 CLASS="FUNCTION"
 525 >lwres_buffer_getuint32()</TT
 526 >
 527 are identical to
 528 <TT
 529 CLASS="FUNCTION"
 530 >lwres_buffer_putuint8()</TT
 531 >
 532 except that they respectively read an unsigned 16-bit or 32-bit integer
 533 in network byte order from
 534 <TT
 535 CLASS="PARAMETER"
 536 ><I
 537 >b</I
 538 ></TT
 539 >.
 540 Similarly,
 541 <TT
 542 CLASS="FUNCTION"
 543 >lwres_buffer_putuint16()</TT
 544 >
 545 and
 546 <TT
 547 CLASS="FUNCTION"
 548 >lwres_buffer_putuint32()</TT
 549 >
 550 writes the unsigned 16-bit or 32-bit integer
 551 <TT
 552 CLASS="PARAMETER"
 553 ><I
 554 >val</I
 555 ></TT
 556 >
 557 to buffer
 558 <TT
 559 CLASS="PARAMETER"
 560 ><I
 561 >b</I
 562 ></TT
 563 >,
 564 in network byte order.</P
 565 ><P
 566 >Arbitrary amounts of data are read or written from a lightweight
 567 resolver buffer with
 568 <TT
 569 CLASS="FUNCTION"
 570 >lwres_buffer_getmem()</TT
 571 >
 572 and
 573 <TT
 574 CLASS="FUNCTION"
 575 >lwres_buffer_putmem()</TT
 576 >
 577 respectively.
 578 <TT
 579 CLASS="FUNCTION"
 580 >lwres_buffer_putmem()</TT
 581 >
 582 copies
 583 <TT
 584 CLASS="PARAMETER"
 585 ><I
 586 >length</I
 587 ></TT
 588 >
 589 bytes of memory at
 590 <TT
 591 CLASS="PARAMETER"
 592 ><I
 593 >base</I
 594 ></TT
 595 >
 596 to
 597 <TT
 598 CLASS="PARAMETER"
 599 ><I
 600 >b</I
 601 ></TT
 602 >.
 603 Conversely,
 604 <TT
 605 CLASS="FUNCTION"
 606 >lwres_buffer_getmem()</TT
 607 >
 608 copies
 609 <TT
 610 CLASS="PARAMETER"
 611 ><I
 612 >length</I
 613 ></TT
 614 >
 615 bytes of memory from
 616 <TT
 617 CLASS="PARAMETER"
 618 ><I
 619 >b</I
 620 ></TT
 621 >
 622 to
 623 <TT
 624 CLASS="PARAMETER"
 625 ><I
 626 >base</I
 627 ></TT
 628 >.</P
 629 ></DIV
 630 ></BODY
 631 ></HTML
 632 >