lwres_buffer.docbook revision 19c7b1a0293498a3e36692c59646ed6e15ffc8d0
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - Copyright (C) 2000, 2001 Internet Software Consortium.
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - Permission to use, copy, modify, and/or distribute this software for any
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - purpose with or without fee is hereby granted, provided that the above
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - copyright notice and this permission notice appear in all copies.
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose - PERFORMANCE OF THIS SOFTWARE.
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose<!-- Converted by db4-upgrade version 1.0 -->
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose <refentryinfo>
81165faf5d951aca69f410713730c26ff048ec44Sumit Bose <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
09d7c105839bfc7447ea0f766413ed86675ca075Sumit Bose </refentryinfo>
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose </copyright>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose </copyright>
08ab0d4ede41a1749e0bc26f78a37a4d10c20db8Sumit Bose <refnamediv>
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose <refpurpose>lightweight resolver buffer management</refpurpose>
84c611c1b7c04cc7735ab54d4e5f48284b79e6fbJan Zeleny </refnamediv>
87ed72b47859e673b636c85f35b85f1546c7ed3dSimo Sorce <refsynopsisdiv>
418e6ccd116eced7ccc75aca999a4c37c67289baJakub Hrozek <funcsynopsis>
87ed72b47859e673b636c85f35b85f1546c7ed3dSimo Sorce<funcsynopsisinfo>
87ed72b47859e673b636c85f35b85f1546c7ed3dSimo Sorce</funcsynopsisinfo>
08ab0d4ede41a1749e0bc26f78a37a4d10c20db8Sumit Bose<funcprototype>
5063dcc5ab685dce325b13b9c1e93cee2a673e60Sumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
cd5033e86bb4065d75188e2b6ef287a4421344c8Sumit Bose <paramdef>void *<parameter>base</parameter></paramdef>
87ed72b47859e673b636c85f35b85f1546c7ed3dSimo Sorce <paramdef>unsigned int <parameter>length</parameter></paramdef>
87ed72b47859e673b636c85f35b85f1546c7ed3dSimo Sorce </funcprototype>
cd5033e86bb4065d75188e2b6ef287a4421344c8Sumit Bose<funcprototype>
cd5033e86bb4065d75188e2b6ef287a4421344c8Sumit Bose<function>lwres_buffer_invalidate</function></funcdef>
cd5033e86bb4065d75188e2b6ef287a4421344c8Sumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
cd5033e86bb4065d75188e2b6ef287a4421344c8Sumit Bose </funcprototype>
cd5033e86bb4065d75188e2b6ef287a4421344c8Sumit Bose<funcprototype>
b1829e54acbc8a010aca7f14b9ffa9625f8c102cSumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
b1829e54acbc8a010aca7f14b9ffa9625f8c102cSumit Bose <paramdef>unsigned int <parameter>n</parameter></paramdef>
b1829e54acbc8a010aca7f14b9ffa9625f8c102cSumit Bose </funcprototype>
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov<funcprototype>
b1829e54acbc8a010aca7f14b9ffa9625f8c102cSumit Bose<function>lwres_buffer_subtract</function></funcdef>
b1829e54acbc8a010aca7f14b9ffa9625f8c102cSumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
b1829e54acbc8a010aca7f14b9ffa9625f8c102cSumit Bose <paramdef>unsigned int <parameter>n</parameter></paramdef>
b1829e54acbc8a010aca7f14b9ffa9625f8c102cSumit Bose </funcprototype>
d2a8b08561e6700bdd4feb988becae4e8f5368ddJakub Hrozek<funcprototype>
d2a8b08561e6700bdd4feb988becae4e8f5368ddJakub Hrozek<function>lwres_buffer_clear</function></funcdef>
c3243e3212f91b69ef9990e2cb4c9339bf2f7888Jakub Hrozek <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
c3243e3212f91b69ef9990e2cb4c9339bf2f7888Jakub Hrozek </funcprototype>
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit Bose<funcprototype>
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit Bose </funcprototype>
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit Bose<funcprototype>
c3243e3212f91b69ef9990e2cb4c9339bf2f7888Jakub Hrozek<function>lwres_buffer_forward</function></funcdef>
c3243e3212f91b69ef9990e2cb4c9339bf2f7888Jakub Hrozek <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
c3243e3212f91b69ef9990e2cb4c9339bf2f7888Jakub Hrozek <paramdef>unsigned int <parameter>n</parameter></paramdef>
c3243e3212f91b69ef9990e2cb4c9339bf2f7888Jakub Hrozek </funcprototype>
d2a8b08561e6700bdd4feb988becae4e8f5368ddJakub Hrozek<funcprototype>
d2a8b08561e6700bdd4feb988becae4e8f5368ddJakub Hrozek<function>lwres_buffer_back</function></funcdef>
d2a8b08561e6700bdd4feb988becae4e8f5368ddJakub Hrozek <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
06424c5ac5ffb871476208155762bb5b73e0b665Jakub Hrozek <paramdef>unsigned int <parameter>n</parameter></paramdef>
d2a8b08561e6700bdd4feb988becae4e8f5368ddJakub Hrozek </funcprototype>
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov<funcprototype>
d2a8b08561e6700bdd4feb988becae4e8f5368ddJakub Hrozeklwres_uint8_t
d2a8b08561e6700bdd4feb988becae4e8f5368ddJakub Hrozek<function>lwres_buffer_getuint8</function></funcdef>
d2a8b08561e6700bdd4feb988becae4e8f5368ddJakub Hrozek <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
d2a8b08561e6700bdd4feb988becae4e8f5368ddJakub Hrozek </funcprototype>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose<funcprototype>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose<function>lwres_buffer_putuint8</function></funcdef>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose <paramdef>lwres_uint8_t <parameter>val</parameter></paramdef>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose </funcprototype>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose<funcprototype>
096a9678919fae460342469989b97fd47d812823Sumit Boselwres_uint16_t
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose<function>lwres_buffer_getuint16</function></funcdef>
096a9678919fae460342469989b97fd47d812823Sumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
096a9678919fae460342469989b97fd47d812823Sumit Bose </funcprototype>
096a9678919fae460342469989b97fd47d812823Sumit Bose<funcprototype>
096a9678919fae460342469989b97fd47d812823Sumit Bose<function>lwres_buffer_putuint16</function></funcdef>
096a9678919fae460342469989b97fd47d812823Sumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
096a9678919fae460342469989b97fd47d812823Sumit Bose <paramdef>lwres_uint16_t <parameter>val</parameter></paramdef>
096a9678919fae460342469989b97fd47d812823Sumit Bose </funcprototype>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose<funcprototype>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Boselwres_uint32_t
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov<function>lwres_buffer_getuint32</function></funcdef>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose </funcprototype>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose<funcprototype>
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov<function>lwres_buffer_putuint32</function></funcdef>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose <paramdef>lwres_uint32_t <parameter>val</parameter></paramdef>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose </funcprototype>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose<funcprototype>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose<function>lwres_buffer_putmem</function></funcdef>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
096a9678919fae460342469989b97fd47d812823Sumit Bose <paramdef>const unsigned char *<parameter>base</parameter></paramdef>
096a9678919fae460342469989b97fd47d812823Sumit Bose <paramdef>unsigned int <parameter>length</parameter></paramdef>
096a9678919fae460342469989b97fd47d812823Sumit Bose </funcprototype>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose<funcprototype>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose<function>lwres_buffer_getmem</function></funcdef>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose <paramdef>unsigned char *<parameter>base</parameter></paramdef>
096a9678919fae460342469989b97fd47d812823Sumit Bose <paramdef>unsigned int <parameter>length</parameter></paramdef>
096a9678919fae460342469989b97fd47d812823Sumit Bose </funcprototype>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose</funcsynopsis>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose </refsynopsisdiv>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose <refsection><info><title>DESCRIPTION</title></info>
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose These functions provide bounds checked access to a region of memory
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose where data is being read or written.
096a9678919fae460342469989b97fd47d812823Sumit Bose They are based on, and similar to, the
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov functions in the ISC library.
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose A buffer is a region of memory, together with a set of related
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose <emphasis>available</emphasis> region are disjoint, and
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov their union is the buffer's region.
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose The used region extends from the beginning of the buffer region to the
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose last used byte.
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose The available region extends from one byte greater than the last used
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose byte to the end of the buffer's region.
096a9678919fae460342469989b97fd47d812823Sumit Bose The size of the used region can be changed using various
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose buffer commands.
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov Initially, the used region is empty.
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose The used region is further subdivided into two disjoint regions: the
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose <emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
096a9678919fae460342469989b97fd47d812823Sumit Bose The union of these two regions is the used region.
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose The consumed region extends from the beginning of the used region to
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov the byte before the <emphasis>current</emphasis> offset (if any).
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose The <emphasis>remaining</emphasis> region the current pointer to the end
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose The size of the consumed region can be changed using various
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose buffer commands.
096a9678919fae460342469989b97fd47d812823Sumit Bose Initially, the consumed region is empty.
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose The <emphasis>active region</emphasis> is an (optional) subregion of the
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose It extends from the current offset to an offset in the
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose remaining region.
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose Initially, the active region is empty.
096a9678919fae460342469989b97fd47d812823Sumit Bose If the current offset advances beyond the chosen offset,
096a9678919fae460342469989b97fd47d812823Sumit Bose the active region will also be empty.
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose /------------entire length---------------\\
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose /----- used region -----\\/-- available --\\
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov +----------------------------------------+
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose | consumed | remaining | |
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose +----------------------------------------+
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov </programlisting>
5e60c73cb91d1659755fb5ea829837db68d46163Sumit Bose a == base of buffer.
096a9678919fae460342469989b97fd47d812823Sumit Bose b == current pointer. Can be anywhere between a and d.
096a9678919fae460342469989b97fd47d812823Sumit Bose c == active pointer. Meaningful between b and d.
096a9678919fae460342469989b97fd47d812823Sumit Bose d == used pointer.
096a9678919fae460342469989b97fd47d812823Sumit Bose e == length of buffer.
db5f9ab3feb85aa444eab20428ca2b98801b6783Jakub Hrozek </programlisting>
096a9678919fae460342469989b97fd47d812823Sumit Bose a-e == entire length of buffer.
096a9678919fae460342469989b97fd47d812823Sumit Bose a-d == used region.
096a9678919fae460342469989b97fd47d812823Sumit Bose a-b == consumed region.
096a9678919fae460342469989b97fd47d812823Sumit Bose b-d == remaining region.
096a9678919fae460342469989b97fd47d812823Sumit Bose b-c == optional active region.
db5f9ab3feb85aa444eab20428ca2b98801b6783Jakub Hrozek</programlisting>
096a9678919fae460342469989b97fd47d812823Sumit Bose initializes the
096a9678919fae460342469989b97fd47d812823Sumit Bose and assocates it with the memory region of size
096a9678919fae460342469989b97fd47d812823Sumit Bose bytes starting at location
096a9678919fae460342469989b97fd47d812823Sumit Bose <para><function>lwres_buffer_invalidate()</function>
096a9678919fae460342469989b97fd47d812823Sumit Bose as invalid. Invalidating a buffer after use is not required,
096a9678919fae460342469989b97fd47d812823Sumit Bose but makes it possible to catch its possible accidental use.
096a9678919fae460342469989b97fd47d812823Sumit Bose The functions
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose respectively increase and decrease the used space in
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose checks for buffer overflow and
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose checks for underflow.
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose These functions do not allocate or deallocate memory.
386a66b1aa18a176e6a06fa126556c9590c373b6Sumit Bose They just change the value of
31dd31b00ad759f256282ef0f7054e60672161ceJakub Hrozek A buffer is re-initialised by
31dd31b00ad759f256282ef0f7054e60672161ceJakub Hrozek The function sets
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov <varname remap="structfield">active</varname>
31dd31b00ad759f256282ef0f7054e60672161ceJakub Hrozek makes the consumed region of buffer
31dd31b00ad759f256282ef0f7054e60672161ceJakub Hrozek empty by setting
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose to zero (the start of the buffer).
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose <para><function>lwres_buffer_forward()</function>
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose increases the consumed region of buffer
10bf907b6d463a5cd776a056cb182bc9f8765bf4Jakub Hrozek bytes, checking for overflow.
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose decreases buffer
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose consumed region by
89ddc9ed474e9ac2b1e7bccb0a58610babf26cf8Jakub Hrozek bytes and checks for underflow.
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose <para><function>lwres_buffer_getuint8()</function>
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose reads an unsigned 8-bit integer from
10bf907b6d463a5cd776a056cb182bc9f8765bf4Jakub Hrozek and returns it.
10bf907b6d463a5cd776a056cb182bc9f8765bf4Jakub Hrozek writes the unsigned 8-bit integer
10bf907b6d463a5cd776a056cb182bc9f8765bf4Jakub Hrozek <para><function>lwres_buffer_getuint16()</function>
10bf907b6d463a5cd776a056cb182bc9f8765bf4Jakub Hrozek are identical to
10bf907b6d463a5cd776a056cb182bc9f8765bf4Jakub Hrozek except that they respectively read an unsigned 16-bit or 32-bit integer
10bf907b6d463a5cd776a056cb182bc9f8765bf4Jakub Hrozek in network byte order from
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose writes the unsigned 16-bit or 32-bit integer
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose in network byte order.
89ddc9ed474e9ac2b1e7bccb0a58610babf26cf8Jakub Hrozek Arbitrary amounts of data are read or written from a lightweight
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose resolver buffer with
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose respectively.
c5711b0279ea85d69fe3c77dfb194360c346e1d7Sumit Bose bytes of memory at
05d935cc9d04f03522d0bb44598d22d99b085926Jakub Hrozek bytes of memory from
05d935cc9d04f03522d0bb44598d22d99b085926Jakub Hrozek </refsection>