0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - This Source Code Form is subject to the terms of the Mozilla Public
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - License, v. 2.0. If a copy of the MPL was not distributed with this
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - file, You can obtain one at http://mozilla.org/MPL/2.0/.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!-- Converted by db4-upgrade version 1.0 -->
83a28ca274521e15086fc39febde507bcc4e145eMark Andrews<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refpurpose>lightweight resolver buffer management</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcsynopsisinfo>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcsynopsisinfo>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_init</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>void *<parameter>base</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>length</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_invalidate</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_add</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>n</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_subtract</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>n</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_clear</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_first</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_forward</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>n</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_back</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>n</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint8</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint8</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint8_t <parameter>val</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint16</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint16</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint16_t <parameter>val</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getuint32</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putuint32</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint32_t <parameter>val</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_putmem</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>const unsigned char *<parameter>base</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>length</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_buffer_getmem</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned char *<parameter>base</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>unsigned int <parameter>length</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>DESCRIPTION</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These functions provide bounds checked access to a region of memory
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein where data is being read or written.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein They are based on, and similar to, the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein functions in the ISC library.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein A buffer is a region of memory, together with a set of related
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <emphasis>available</emphasis> region are disjoint, and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein their union is the buffer's region.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The used region extends from the beginning of the buffer region to the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein last used byte.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The available region extends from one byte greater than the last used
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein byte to the end of the buffer's region.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The size of the used region can be changed using various
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein buffer commands.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Initially, the used region is empty.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The used region is further subdivided into two disjoint regions: the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The union of these two regions is the used region.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The consumed region extends from the beginning of the used region to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the byte before the <emphasis>current</emphasis> offset (if any).
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The <emphasis>remaining</emphasis> region the current pointer to the end
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The size of the consumed region can be changed using various
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein buffer commands.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Initially, the consumed region is empty.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The <emphasis>active region</emphasis> is an (optional) subregion of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein It extends from the current offset to an offset in the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein remaining region.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Initially, the active region is empty.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If the current offset advances beyond the chosen offset,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the active region will also be empty.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson /------------entire length---------------\\
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson /----- used region -----\\/-- available --\\
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson +----------------------------------------+
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson | consumed | remaining | |
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson +----------------------------------------+
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </programlisting>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson a == base of buffer.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson b == current pointer. Can be anywhere between a and d.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson c == active pointer. Meaningful between b and d.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson d == used pointer.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson e == length of buffer.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </programlisting>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson a-e == entire length of buffer.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson a-d == used region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson a-b == consumed region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson b-d == remaining region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson b-c == optional active region.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</programlisting>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein initializes the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and assocates it with the memory region of size
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bytes starting at location
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_buffer_invalidate()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein as invalid. Invalidating a buffer after use is not required,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein but makes it possible to catch its possible accidental use.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The functions
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein respectively increase and decrease the used space in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein checks for buffer overflow and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein checks for underflow.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These functions do not allocate or deallocate memory.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein They just change the value of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein A buffer is re-initialised by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The function sets
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein makes the consumed region of buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein empty by setting
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to zero (the start of the buffer).
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_buffer_forward()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein increases the consumed region of buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bytes, checking for overflow.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein decreases buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein consumed region by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bytes and checks for underflow.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_buffer_getuint8()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein reads an unsigned 8-bit integer from
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and returns it.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein writes the unsigned 8-bit integer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_buffer_getuint16()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein are identical to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein except that they respectively read an unsigned 16-bit or 32-bit integer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in network byte order from
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein writes the unsigned 16-bit or 32-bit integer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in network byte order.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Arbitrary amounts of data are read or written from a lightweight
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein resolver buffer with
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein respectively.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bytes of memory at
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bytes of memory from
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>