- import of strongswan-2.7.0
- applied patch for charon
This commit is contained in:
Martin Willi
@@ -0,0 +1,378 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_buffer.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_buffer</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_buffer_init</refname>
|
||||
<refname>lwres_buffer_invalidate</refname>
|
||||
<refname>lwres_buffer_add</refname>
|
||||
<refname>lwres_buffer_subtract</refname>
|
||||
<refname>lwres_buffer_clear</refname>
|
||||
<refname>lwres_buffer_first</refname>
|
||||
<refname>lwres_buffer_forward</refname>
|
||||
<refname>lwres_buffer_back</refname>
|
||||
<refname>lwres_buffer_getuint8</refname>
|
||||
<refname>lwres_buffer_putuint8</refname>
|
||||
<refname>lwres_buffer_getuint16</refname>
|
||||
<refname>lwres_buffer_putuint16</refname>
|
||||
<refname>lwres_buffer_getuint32</refname>
|
||||
<refname>lwres_buffer_putuint32</refname>
|
||||
<refname>lwres_buffer_putmem</refname>
|
||||
<refname>lwres_buffer_getmem</refname>
|
||||
<refpurpose>lightweight resolver buffer management</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <lwres/lwbuffer.h>
|
||||
</funcsynopsisinfo>
|
||||
|
||||
<funcprototype>
|
||||
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_init</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>void *base</paramdef>
|
||||
<paramdef>unsigned int length</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_invalidate</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_add</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>unsigned int n</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_subtract</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>unsigned int n</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_clear</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_first</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_forward</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>unsigned int n</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_back</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>unsigned int n</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_uint8_t
|
||||
<function>lwres_buffer_getuint8</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_putuint8</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_uint8_t val</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_uint16_t
|
||||
<function>lwres_buffer_getuint16</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_putuint16</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_uint16_t val</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_uint32_t
|
||||
<function>lwres_buffer_getuint32</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_putuint32</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_uint32_t val</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_putmem</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>const unsigned char *base</paramdef>
|
||||
<paramdef>unsigned int length</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_getmem</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>unsigned char *base</paramdef>
|
||||
<paramdef>unsigned int length</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
These functions provide bounds checked access to a region of memory
|
||||
where data is being read or written.
|
||||
They are based on, and similar to, the
|
||||
<literal>isc_buffer_</literal>
|
||||
functions in the ISC library.
|
||||
</para>
|
||||
<para>
|
||||
A buffer is a region of memory, together with a set of related
|
||||
subregions.
|
||||
The <emphasis>used region</emphasis> and the
|
||||
<emphasis>available</emphasis> region are disjoint, and
|
||||
their union is the buffer's region.
|
||||
The used region extends from the beginning of the buffer region to the
|
||||
last used byte.
|
||||
The available region extends from one byte greater than the last used
|
||||
byte to the end of the buffer's region.
|
||||
The size of the used region can be changed using various
|
||||
buffer commands.
|
||||
Initially, the used region is empty.
|
||||
</para>
|
||||
<para>
|
||||
The used region is further subdivided into two disjoint regions: the
|
||||
<emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
|
||||
The union of these two regions is the used region.
|
||||
The consumed region extends from the beginning of the used region to
|
||||
the byte before the <emphasis>current</emphasis> offset (if any).
|
||||
The <emphasis>remaining</emphasis> region the current pointer to the end of the used
|
||||
region.
|
||||
The size of the consumed region can be changed using various
|
||||
buffer commands.
|
||||
Initially, the consumed region is empty.
|
||||
</para>
|
||||
<para>
|
||||
The <emphasis>active region</emphasis> is an (optional) subregion of the remaining
|
||||
region.
|
||||
It extends from the current offset to an offset in the
|
||||
remaining region.
|
||||
Initially, the active region is empty.
|
||||
If the current offset advances beyond the chosen offset,
|
||||
the active region will also be empty.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
|
||||
/------------entire length---------------\\
|
||||
/----- used region -----\\/-- available --\\
|
||||
+----------------------------------------+
|
||||
| consumed | remaining | |
|
||||
+----------------------------------------+
|
||||
a b c d e
|
||||
|
||||
a == base of buffer.
|
||||
b == current pointer. Can be anywhere between a and d.
|
||||
c == active pointer. Meaningful between b and d.
|
||||
d == used pointer.
|
||||
e == length of buffer.
|
||||
|
||||
a-e == entire length of buffer.
|
||||
a-d == used region.
|
||||
a-b == consumed region.
|
||||
b-d == remaining region.
|
||||
b-c == optional active region.
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_init()</function>
|
||||
initializes the
|
||||
<type>lwres_buffer_t</type>
|
||||
<parameter>*b</parameter>
|
||||
and assocates it with the memory region of size
|
||||
<parameter>length</parameter>
|
||||
bytes starting at location
|
||||
<parameter>base.</parameter>
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_invalidate()</function>
|
||||
marks the buffer
|
||||
<parameter>*b</parameter>
|
||||
as invalid. Invalidating a buffer after use is not required,
|
||||
but makes it possible to catch its possible accidental use.
|
||||
</para>
|
||||
<para>
|
||||
The functions
|
||||
<function>lwres_buffer_add()</function>
|
||||
and
|
||||
<function>lwres_buffer_subtract()</function>
|
||||
respectively increase and decrease the used space in
|
||||
buffer
|
||||
<parameter>*b</parameter>
|
||||
by
|
||||
<parameter>n</parameter>
|
||||
bytes.
|
||||
<function>lwres_buffer_add()</function>
|
||||
checks for buffer overflow and
|
||||
<function>lwres_buffer_subtract()</function>
|
||||
checks for underflow.
|
||||
These functions do not allocate or deallocate memory.
|
||||
They just change the value of
|
||||
<structfield>used</structfield>.
|
||||
</para>
|
||||
<para>
|
||||
A buffer is re-initialised by
|
||||
<function>lwres_buffer_clear()</function>.
|
||||
The function sets
|
||||
<structfield>used</structfield> ,
|
||||
<structfield>current</structfield>
|
||||
and
|
||||
<structfield>active</structfield>
|
||||
to zero.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_first</function>
|
||||
makes the consumed region of buffer
|
||||
<parameter>*p</parameter>
|
||||
empty by setting
|
||||
<structfield>current</structfield>
|
||||
to zero (the start of the buffer).
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_forward()</function>
|
||||
increases the consumed region of buffer
|
||||
<parameter>*b</parameter>
|
||||
by
|
||||
<parameter>n</parameter>
|
||||
bytes, checking for overflow.
|
||||
Similarly,
|
||||
<function>lwres_buffer_back()</function>
|
||||
decreases buffer
|
||||
<parameter>b</parameter>'s
|
||||
consumed region by
|
||||
<parameter>n</parameter>
|
||||
bytes and checks for underflow.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_getuint8()</function>
|
||||
reads an unsigned 8-bit integer from
|
||||
<parameter>*b</parameter>
|
||||
and returns it.
|
||||
<function>lwres_buffer_putuint8()</function>
|
||||
writes the unsigned 8-bit integer
|
||||
<parameter>val</parameter>
|
||||
to buffer
|
||||
<parameter>*b</parameter>.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_getuint16()</function>
|
||||
and
|
||||
<function>lwres_buffer_getuint32()</function>
|
||||
are identical to
|
||||
<function>lwres_buffer_putuint8()</function>
|
||||
except that they respectively read an unsigned 16-bit or 32-bit integer
|
||||
in network byte order from
|
||||
<parameter>b</parameter>.
|
||||
Similarly,
|
||||
<function>lwres_buffer_putuint16()</function>
|
||||
and
|
||||
<function>lwres_buffer_putuint32()</function>
|
||||
writes the unsigned 16-bit or 32-bit integer
|
||||
<parameter>val</parameter>
|
||||
to buffer
|
||||
<parameter>b</parameter>,
|
||||
in network byte order.
|
||||
</para>
|
||||
<para>
|
||||
Arbitrary amounts of data are read or written from a lightweight
|
||||
resolver buffer with
|
||||
<function>lwres_buffer_getmem()</function>
|
||||
and
|
||||
<function>lwres_buffer_putmem()</function>
|
||||
respectively.
|
||||
<function>lwres_buffer_putmem()</function>
|
||||
copies
|
||||
<parameter>length</parameter>
|
||||
bytes of memory at
|
||||
<parameter>base</parameter>
|
||||
to
|
||||
<parameter>b</parameter>.
|
||||
Conversely,
|
||||
<function>lwres_buffer_getmem()</function>
|
||||
copies
|
||||
<parameter>length</parameter>
|
||||
bytes of memory from
|
||||
<parameter>b</parameter>
|
||||
to
|
||||
<parameter>base</parameter>.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
Reference in New Issue
Block a user