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