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

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