PageRenderTime 16ms CodeModel.GetById 6ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 2ms

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

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 394 lines | 369 code | 25 blank | 0 comment | 0 complexity | 3f9c06e59886e4cd9665ee85f47a9a1a MD5 | raw file
  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  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<!-- $Id: lwres_buffer.docbook,v 1.10 2007/06/18 23:47:51 tbox Exp $ -->
 22<refentry>
 23  <refentryinfo>
 24    <date>Jun 30, 2000</date>
 25  </refentryinfo>
 26
 27  <refmeta>
 28    <refentrytitle>lwres_buffer</refentrytitle>
 29    <manvolnum>3</manvolnum>
 30    <refmiscinfo>BIND9</refmiscinfo>
 31  </refmeta>
 32
 33  <docinfo>
 34    <copyright>
 35      <year>2004</year>
 36      <year>2005</year>
 37      <year>2007</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>
 77void
 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>
 86void
 87<function>lwres_buffer_invalidate</function></funcdef>
 88        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
 89        </funcprototype>
 90<funcprototype>
 91        <funcdef>
 92void
 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>
100void
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>
108void
109<function>lwres_buffer_clear</function></funcdef>
110        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
111        </funcprototype>
112
113<funcprototype>
114        <funcdef>
115void
116<function>lwres_buffer_first</function></funcdef>
117        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
118        </funcprototype>
119
120<funcprototype>
121        <funcdef>
122void
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>
130void
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>
138lwres_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>
145void
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>
153lwres_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>
160void
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>
168lwres_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>
175void
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>
183void
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>
192void
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-->