diff options
Diffstat (limited to 'lib/lwres/man/lwres_buffer.docbook')
| -rw-r--r-- | lib/lwres/man/lwres_buffer.docbook | 387 |
1 files changed, 387 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_buffer.docbook b/lib/lwres/man/lwres_buffer.docbook new file mode 100644 index 0000000..b7a38d0 --- /dev/null +++ b/lib/lwres/man/lwres_buffer.docbook @@ -0,0 +1,387 @@ +<!-- + - Copyright (C) Internet Systems Consortium, Inc. ("ISC") + - + - This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - + - See the COPYRIGHT file distributed with this work for additional + - information regarding copyright ownership. +--> + +<!-- Converted by db4-upgrade version 1.0 --> +<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0"> + <info> + <date>2007-06-18</date> + </info> + <refentryinfo> + <corpname>ISC</corpname> + <corpauthor>Internet Systems Consortium, Inc.</corpauthor> + </refentryinfo> + + <refmeta> + <refentrytitle>lwres_buffer</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> + + <docinfo> + <copyright> + <year>2000</year> + <year>2001</year> + <year>2004</year> + <year>2005</year> + <year>2007</year> + <year>2014</year> + <year>2015</year> + <year>2016</year> + <year>2018</year> + <year>2019</year> + <holder>Internet Systems Consortium, Inc. ("ISC")</holder> + </copyright> + </docinfo> + + <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 *<parameter>b</parameter></paramdef> + <paramdef>void *<parameter>base</parameter></paramdef> + <paramdef>unsigned int <parameter>length</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +void +<function>lwres_buffer_invalidate</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> +<funcprototype> + <funcdef> +void +<function>lwres_buffer_add</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>unsigned int <parameter>n</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +void +<function>lwres_buffer_subtract</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>unsigned int <parameter>n</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +void +<function>lwres_buffer_clear</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +void +<function>lwres_buffer_first</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +void +<function>lwres_buffer_forward</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>unsigned int <parameter>n</parameter></paramdef> + </funcprototype> +<funcprototype> + + <funcdef> +void +<function>lwres_buffer_back</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>unsigned int <parameter>n</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +uint8_t +<function>lwres_buffer_getuint8</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +void +<function>lwres_buffer_putuint8</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>uint8_t <parameter>val</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +uint16_t +<function>lwres_buffer_getuint16</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +void +<function>lwres_buffer_putuint16</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>uint16_t <parameter>val</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +uint32_t +<function>lwres_buffer_getuint32</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +void +<function>lwres_buffer_putuint32</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>uint32_t <parameter>val</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +void +<function>lwres_buffer_putmem</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>const unsigned char *<parameter>base</parameter></paramdef> + <paramdef>unsigned int <parameter>length</parameter></paramdef> + </funcprototype> + +<funcprototype> + <funcdef> +void +<function>lwres_buffer_getmem</function></funcdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>unsigned char *<parameter>base</parameter></paramdef> + <paramdef>unsigned int <parameter>length</parameter></paramdef> + </funcprototype> + +</funcsynopsis> + </refsynopsisdiv> + + <refsection><info><title>DESCRIPTION</title></info> + + + <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 + </programlisting> + </para> + <para><programlisting> + 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. + </programlisting> + </para> + <para><programlisting> + 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 + <varname remap="structfield">used</varname>. + </para> + <para> + A buffer is re-initialised by + <function>lwres_buffer_clear()</function>. + The function sets + <varname remap="structfield">used</varname>, + <varname remap="structfield">current</varname> + and + <varname remap="structfield">active</varname> + to zero. + </para> + <para><function>lwres_buffer_first</function> + makes the consumed region of buffer + <parameter>*p</parameter> + empty by setting + <varname remap="structfield">current</varname> + 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> + </refsection> +</refentry> |