lwres_buffer.docbook revision dafcb997e390efa4423883dafd100c975c4095d6
8c1aa8573dd85774ac8921dc0482b91d73e8b8b6Mark Andrews<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
8c1aa8573dd85774ac8921dc0482b91d73e8b8b6Mark Andrews - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
96ab25294b028270eb1be867613df8a6c999b332David Lawrence - Copyright (C) 2001 Internet Software Consortium.
96ab25294b028270eb1be867613df8a6c999b332David Lawrence - Permission to use, copy, modify, and distribute this software for any
96ab25294b028270eb1be867613df8a6c999b332David Lawrence - purpose with or without fee is hereby granted, provided that the above
96ab25294b028270eb1be867613df8a6c999b332David Lawrence - copyright notice and this permission notice appear in all copies.
96ab25294b028270eb1be867613df8a6c999b332David Lawrence - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
e68de4a7dbf5b6a1b2ff3f4f4dd8adf80b80525bBrian Wellington - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
96ab25294b028270eb1be867613df8a6c999b332David Lawrence - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
96ab25294b028270eb1be867613df8a6c999b332David Lawrence - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
96ab25294b028270eb1be867613df8a6c999b332David Lawrence - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
5aa96829fdd12f30a2e9f717e66d44a4698b0675Andreas Gustafsson - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
5aa96829fdd12f30a2e9f717e66d44a4698b0675Andreas Gustafsson - PERFORMANCE OF THIS SOFTWARE.
5aa96829fdd12f30a2e9f717e66d44a4698b0675Andreas Gustafsson<!-- $Id: lwres_buffer.docbook,v 1.4 2004/03/05 05:12:56 marka Exp $ -->
e2894b0e5007e49f5b21be9113e41419ca8489a0Brian Wellington<refentryinfo>
e2894b0e5007e49f5b21be9113e41419ca8489a0Brian Wellington</refentryinfo>
e405739af20dcdc6c7f604548e78806a0d1515c5Brian Wellington<refpurpose>lightweight resolver buffer management</refpurpose>
428b78e56dc10ea220fadfed11242ceb1d51d0e3Andreas Gustafsson<refsynopsisdiv>
b719a598e77aada962b3a05cb00179dc929d3939Andreas Gustafsson<funcsynopsisinfo>
428b78e56dc10ea220fadfed11242ceb1d51d0e3Andreas Gustafsson</funcsynopsisinfo>
428b78e56dc10ea220fadfed11242ceb1d51d0e3Andreas Gustafsson<funcprototype>
428b78e56dc10ea220fadfed11242ceb1d51d0e3Andreas Gustafsson<function>lwres_buffer_init</function></funcdef>
b74e73c5b4b299da20a6b196b68b9068d376ff35Mark Andrews</funcprototype>
b74e73c5b4b299da20a6b196b68b9068d376ff35Mark Andrews<funcprototype>
d68e4b66b1075e556b480f8bfb607aeba5da46f6Andreas Gustafsson<function>lwres_buffer_invalidate</function></funcdef>
d68e4b66b1075e556b480f8bfb607aeba5da46f6Andreas Gustafsson</funcprototype>
d68e4b66b1075e556b480f8bfb607aeba5da46f6Andreas Gustafsson<funcprototype>
d68e4b66b1075e556b480f8bfb607aeba5da46f6Andreas Gustafsson<function>lwres_buffer_add</function></funcdef>
e44d56866bd609e066380cbef414e6ce11a08976Andreas Gustafsson</funcprototype>
84c4c99c9e2cf14fb9ef6f6815a9fdb824475423Michael Sawyer<funcprototype>
f204bdd8e6703ff0ef1adf0a2c407202418a936dDavid Lawrence<function>lwres_buffer_subtract</function></funcdef>
f204bdd8e6703ff0ef1adf0a2c407202418a936dDavid Lawrence</funcprototype>
f204bdd8e6703ff0ef1adf0a2c407202418a936dDavid Lawrence<funcprototype>
0df2335526caaebd8639129fd0327a6cc97060eaDavid Lawrence<function>lwres_buffer_clear</function></funcdef>
f204bdd8e6703ff0ef1adf0a2c407202418a936dDavid Lawrence</funcprototype>
8b31f5630f6345f686449f8a84c33c0813283e42Andreas Gustafsson<funcprototype>
8b31f5630f6345f686449f8a84c33c0813283e42Andreas Gustafsson<function>lwres_buffer_first</function></funcdef>
13c32cb589e571e9204dbb091e145809288c9c21David Lawrence</funcprototype>
13c32cb589e571e9204dbb091e145809288c9c21David Lawrence<funcprototype>
822f118444dcaddaf977bc73e958b2f755e4ddfdAndreas Gustafsson<function>lwres_buffer_forward</function></funcdef>
822f118444dcaddaf977bc73e958b2f755e4ddfdAndreas Gustafsson</funcprototype>
f204bdd8e6703ff0ef1adf0a2c407202418a936dDavid Lawrence<funcprototype>
406ce0cd9633188a79c008e8f7c8092fa54bc98cJames Brister<function>lwres_buffer_back</function></funcdef>
a797a75953e21b514427d188bf5d5051419c10adBrian Wellington</funcprototype>
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrence<funcprototype>
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrence<function>lwres_buffer_getuint8</function></funcdef>
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrence</funcprototype>
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrence<funcprototype>
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrence<function>lwres_buffer_putuint8</function></funcdef>
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrence</funcprototype>
c244584cad2a71276e60919bf2c80c7d79dc073bDavid Lawrence<funcprototype>
abeb505bb6c1400dde1a40d0bff7b3a435666e1cMark Andrewslwres_uint16_t
727eef0cbc8bf889ddb3b58eb89e9ea2c3b4b047Andreas Gustafsson<function>lwres_buffer_getuint16</function></funcdef>
57b3597444bc8716459f0fb3022b2c12f4eee2aeAndreas Gustafsson</funcprototype>
727eef0cbc8bf889ddb3b58eb89e9ea2c3b4b047Andreas Gustafsson<funcprototype>
26c86a6fc85c89447d23d4a3e34b11157a2ff6f4Andreas Gustafsson<function>lwres_buffer_putuint16</function></funcdef>
26c86a6fc85c89447d23d4a3e34b11157a2ff6f4Andreas Gustafsson</funcprototype>
b3157263ee12a5792737f09b708d3fc65ca99e01Andreas Gustafsson<funcprototype>
b3157263ee12a5792737f09b708d3fc65ca99e01Andreas Gustafsson<function>lwres_buffer_getuint32</function></funcdef>
b90d3f516fd62514ff0b06a6ee0311d7ab5fbbb4Brian Wellington</funcprototype>
b90d3f516fd62514ff0b06a6ee0311d7ab5fbbb4Brian Wellington<funcprototype>
7bb1e299e133de5d530aa4cb545f4130aabf5235Andreas Gustafsson<function>lwres_buffer_putuint32</function></funcdef>
7bb1e299e133de5d530aa4cb545f4130aabf5235Andreas Gustafsson</funcprototype>
482b9dae17bc5dc4e51b78d3c5b1a18c7c1adae9Andreas Gustafsson<funcprototype>
34ea3c6fd940a8514b5ec609491f823263a735c7Michael Sawyer<function>lwres_buffer_putmem</function></funcdef>
26c86a6fc85c89447d23d4a3e34b11157a2ff6f4Andreas Gustafsson<paramdef>const unsigned char *base</paramdef>
8ae26e9f87560f9d2e495328d573c25af81c49beMark Andrews</funcprototype>
3c671ac666de8a7dcd7bd02afa20968da0b85bbdMark Andrews<funcprototype>
3c671ac666de8a7dcd7bd02afa20968da0b85bbdMark Andrews<function>lwres_buffer_getmem</function></funcdef>
58c42ee18c186b2151ced62f64aa4ca23cff4a1dJames Brister</funcprototype>
58c42ee18c186b2151ced62f64aa4ca23cff4a1dJames Brister</funcsynopsis>
58c42ee18c186b2151ced62f64aa4ca23cff4a1dJames Brister</refsynopsisdiv>
242dfd9cc6901a5e02dae94acdecdb91e78ea07cMark AndrewsThese functions provide bounds checked access to a region of memory
77771185071bf74d53378f1a3099a04d2af5153eBrian Wellingtonwhere data is being read or written.
77771185071bf74d53378f1a3099a04d2af5153eBrian WellingtonThey are based on, and similar to, the
77771185071bf74d53378f1a3099a04d2af5153eBrian Wellingtonfunctions in the ISC library.
0d5d8e2bbf2c0c129f0416f24758a0925ce12be8James BristerA buffer is a region of memory, together with a set of related
99f3a24e69edbb19e4fe7f2fb0a72c478f8c3cafJames Brister<emphasis>available</emphasis> region are disjoint, and
aa79283a0d97d5d77d3c17bcb1756035eabe647aAndreas Gustafssontheir union is the buffer's region.
aa79283a0d97d5d77d3c17bcb1756035eabe647aAndreas GustafssonThe used region extends from the beginning of the buffer region to the
f204bdd8e6703ff0ef1adf0a2c407202418a936dDavid Lawrencelast used byte.
aa79283a0d97d5d77d3c17bcb1756035eabe647aAndreas GustafssonThe available region extends from one byte greater than the last used
aa79283a0d97d5d77d3c17bcb1756035eabe647aAndreas Gustafssonbyte to the end of the buffer's region.
aa79283a0d97d5d77d3c17bcb1756035eabe647aAndreas GustafssonThe size of the used region can be changed using various
aa79283a0d97d5d77d3c17bcb1756035eabe647aAndreas Gustafssonbuffer commands.
aa79283a0d97d5d77d3c17bcb1756035eabe647aAndreas GustafssonInitially, the used region is empty.
aa79283a0d97d5d77d3c17bcb1756035eabe647aAndreas GustafssonThe used region is further subdivided into two disjoint regions: the
f204bdd8e6703ff0ef1adf0a2c407202418a936dDavid Lawrence<emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
0bfcec250f9705a1211d0374f0fc1049960de84bMark AndrewsThe union of these two regions is the used region.
0bfcec250f9705a1211d0374f0fc1049960de84bMark AndrewsThe consumed region extends from the beginning of the used region to
b5f24a6988e04710bee0281b03b7e168358ac868Andreas Gustafssonthe byte before the <emphasis>current</emphasis> offset (if any).
b5f24a6988e04710bee0281b03b7e168358ac868Andreas GustafssonThe <emphasis>remaining</emphasis> region the current pointer to the end of the used
379bd2c19cec393f56a2e9c42cc87fc8213a1b62James BristerThe size of the consumed region can be changed using various
379bd2c19cec393f56a2e9c42cc87fc8213a1b62James Bristerbuffer commands.
379bd2c19cec393f56a2e9c42cc87fc8213a1b62James BristerInitially, the consumed region is empty.
379bd2c19cec393f56a2e9c42cc87fc8213a1b62James BristerThe <emphasis>active region</emphasis> is an (optional) subregion of the remaining
c24265935e70d17279153b3cde43e3f6c3527577Andreas GustafssonIt extends from the current offset to an offset in the
bedfa169b4cc5511b34c0c4a54c5b8aae364babeJames Bristerremaining region.
bedfa169b4cc5511b34c0c4a54c5b8aae364babeJames BristerInitially, the active region is empty.
bedfa169b4cc5511b34c0c4a54c5b8aae364babeJames BristerIf the current offset advances beyond the chosen offset,
bedfa169b4cc5511b34c0c4a54c5b8aae364babeJames Bristerthe active region will also be empty.
d85552c450141012e7cbeaacc77fb9575b0bb4cbJames Brister<programlisting>
d85552c450141012e7cbeaacc77fb9575b0bb4cbJames Brister /------------entire length---------------\\
47c196192afa37b2dea728e52579779f190bf07fJames Brister /----- used region -----\\/-- available --\\
47c196192afa37b2dea728e52579779f190bf07fJames Brister +----------------------------------------+
29196ffb72a1337c72ffd6d52f1c8348f84c644eJames Brister | consumed | remaining | |
47c196192afa37b2dea728e52579779f190bf07fJames Brister +----------------------------------------+
94c5757a7a2d98b4de3e7a68cfe330d59450f09eAndreas Gustafsson a == base of buffer.
f3b52d9fe5e7e851adecad4eec8952cceda47592Brian Wellington b == current pointer. Can be anywhere between a and d.
94c5757a7a2d98b4de3e7a68cfe330d59450f09eAndreas Gustafsson c == active pointer. Meaningful between b and d.
94c5757a7a2d98b4de3e7a68cfe330d59450f09eAndreas Gustafsson d == used pointer.
94c5757a7a2d98b4de3e7a68cfe330d59450f09eAndreas Gustafsson e == length of buffer.
f3b52d9fe5e7e851adecad4eec8952cceda47592Brian Wellington a-e == entire length of buffer.
71a4339351de0d8233d61025a667ec4dc3e0f868James Brister a-d == used region.
71a4339351de0d8233d61025a667ec4dc3e0f868James Brister a-b == consumed region.
71a4339351de0d8233d61025a667ec4dc3e0f868James Brister b-d == remaining region.
71a4339351de0d8233d61025a667ec4dc3e0f868James Brister b-c == optional active region.
71a4339351de0d8233d61025a667ec4dc3e0f868James Brister</programlisting>
0380c44d0238a88e167526954d630d071739ed28Mark Andrewsinitializes the
a6733246eafeb43755ce6d7ec3627ac4209cbccbMark Andrewsand assocates it with the memory region of size
36bcb04af27e050ddc04b2ff37dbeafc84538fd4Brian Wellingtonbytes starting at location
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrence<function>lwres_buffer_invalidate()</function>
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrencemarks the buffer
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrenceas invalid. Invalidating a buffer after use is not required,
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrencebut makes it possible to catch its possible accidental use.
9c11326b18c69b9b2fd6102d80fbd568ae6bd31eAndreas Gustafsson<function>lwres_buffer_subtract()</function>
c78dc8b001ba46ef1edb784635c3ba7b3e4456ceJames Bristerrespectively increase and decrease the used space in
d5399cc351a549db957185993b320a3bffa40e41James Bristerchecks for buffer overflow and
d5399cc351a549db957185993b320a3bffa40e41James Bristerchecks for underflow.
40f349ad1f2f0a63ef2784b8affcd44dc660b39cJames BristerThese functions do not allocate or deallocate memory.
40f349ad1f2f0a63ef2784b8affcd44dc660b39cJames BristerThey just change the value of
69b691c9624f31e59b8d128ada902a82127c15a3James BristerA buffer is re-initialised by
69b691c9624f31e59b8d128ada902a82127c15a3James BristerThe function sets
98c2f9a11185b8a5dd601798990612beb6d1578eJames Bristermakes the consumed region of buffer
98c2f9a11185b8a5dd601798990612beb6d1578eJames Bristerempty by setting
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrenceto zero (the start of the buffer).
705cb05a187558959d20ec2c31e06de8e96f61b2David Lawrenceincreases the consumed region of buffer
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrencebytes, checking for overflow.
0b056755b2f423ba5f6adac8f7851d78f7d11437David Lawrencedecreases buffer
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrenceconsumed region by
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrencebytes and checks for underflow.
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrencereads an unsigned 8-bit integer from
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrenceand returns it.
0640343258a99230c62e39dfbbe1505e3a970ee8Andreas Gustafssonwrites the unsigned 8-bit integer
d98c74e2ec5b96bd22aa4ed6d893e8993787493bMichael Graffare identical to
d03d4524993ecf5da72694907cb8581eadbe5c4dBrian Wellington<function>lwres_buffer_putuint8()</function>
d03d4524993ecf5da72694907cb8581eadbe5c4dBrian Wellingtonexcept that they respectively read an unsigned 16-bit or 32-bit integer
d03d4524993ecf5da72694907cb8581eadbe5c4dBrian Wellingtonin network byte order from
75f6c57d9544aa77a3b1a04587b4702c07343c90Brian Wellington<function>lwres_buffer_putuint16()</function>
c8df84cb389994b4eaf549f5851e70d18e2d063fAndreas Gustafsson<function>lwres_buffer_putuint32()</function>
f34984369fbc87f6cc5c5d1059303377a1724d79James Bristerwrites the unsigned 16-bit or 32-bit integer
76a191c4202a4839e4ce598ec91f0c0d12f630aaAndreas Gustafssonin network byte order.
76a191c4202a4839e4ce598ec91f0c0d12f630aaAndreas GustafssonArbitrary amounts of data are read or written from a lightweight
9151d6e15cb9c639a3dca083d7f6e9094f6b89caDavid Lawrenceresolver buffer with
fef059dcec0f7f83b09b9ce30b91b21a51d9c481Andreas Gustafsson<function>lwres_buffer_getmem()</function>
af602636644fdfaabc331bd926b0aabb9432e152Brian Wellingtonbytes of memory at
b3aaa872e12e5c8658271bde8e4dd85d015e823fAndreas Gustafsson<function>lwres_buffer_getmem()</function>
389f2ccc2f5f00a11a14114d40492f7ac8249fa7Olafur Gudmundssonbytes of memory from