1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 3 [<!ENTITY mdash "—">]> 4<!-- 5 - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC") 6 - Copyright (C) 2000, 2001 Internet Software Consortium. 7 - 8 - Permission to use, copy, modify, and/or distribute this software for any 9 - purpose with or without fee is hereby granted, provided that the above 10 - copyright notice and this permission notice appear in all copies. 11 - 12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 18 - PERFORMANCE OF THIS SOFTWARE. 19--> 20 21<refentry> 22 <refentryinfo> 23 <date>June 18, 2007</date> 24 </refentryinfo> 25 26 <refmeta> 27 <refentrytitle>lwres_buffer</refentrytitle> 28 <manvolnum>3</manvolnum> 29 <refmiscinfo>BIND9</refmiscinfo> 30 </refmeta> 31 32 <docinfo> 33 <copyright> 34 <year>2004</year> 35 <year>2005</year> 36 <year>2007</year> 37 <year>2014</year> 38 <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 39 </copyright> 40 <copyright> 41 <year>2000</year> 42 <year>2001</year> 43 <holder>Internet Software Consortium.</holder> 44 </copyright> 45 </docinfo> 46 47 <refnamediv> 48 <refname>lwres_buffer_init</refname> 49 <refname>lwres_buffer_invalidate</refname> 50 <refname>lwres_buffer_add</refname> 51 <refname>lwres_buffer_subtract</refname> 52 <refname>lwres_buffer_clear</refname> 53 <refname>lwres_buffer_first</refname> 54 <refname>lwres_buffer_forward</refname> 55 <refname>lwres_buffer_back</refname> 56 <refname>lwres_buffer_getuint8</refname> 57 <refname>lwres_buffer_putuint8</refname> 58 <refname>lwres_buffer_getuint16</refname> 59 <refname>lwres_buffer_putuint16</refname> 60 <refname>lwres_buffer_getuint32</refname> 61 <refname>lwres_buffer_putuint32</refname> 62 <refname>lwres_buffer_putmem</refname> 63 <refname>lwres_buffer_getmem</refname> 64 <refpurpose>lightweight resolver buffer management</refpurpose> 65 </refnamediv> 66 67 <refsynopsisdiv> 68 69 <funcsynopsis> 70<funcsynopsisinfo> 71#include <lwres/lwbuffer.h> 72</funcsynopsisinfo> 73 74<funcprototype> 75 76 <funcdef> 77void 78<function>lwres_buffer_init</function></funcdef> 79 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 80 <paramdef>void *<parameter>base</parameter></paramdef> 81 <paramdef>unsigned int <parameter>length</parameter></paramdef> 82 </funcprototype> 83 84<funcprototype> 85 <funcdef> 86void 87<function>lwres_buffer_invalidate</function></funcdef> 88 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 89 </funcprototype> 90<funcprototype> 91 <funcdef> 92void 93<function>lwres_buffer_add</function></funcdef> 94 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 95 <paramdef>unsigned int <parameter>n</parameter></paramdef> 96 </funcprototype> 97 98<funcprototype> 99 <funcdef> 100void 101<function>lwres_buffer_subtract</function></funcdef> 102 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 103 <paramdef>unsigned int <parameter>n</parameter></paramdef> 104 </funcprototype> 105 106<funcprototype> 107 <funcdef> 108void 109<function>lwres_buffer_clear</function></funcdef> 110 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 111 </funcprototype> 112 113<funcprototype> 114 <funcdef> 115void 116<function>lwres_buffer_first</function></funcdef> 117 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 118 </funcprototype> 119 120<funcprototype> 121 <funcdef> 122void 123<function>lwres_buffer_forward</function></funcdef> 124 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 125 <paramdef>unsigned int <parameter>n</parameter></paramdef> 126 </funcprototype> 127<funcprototype> 128 129 <funcdef> 130void 131<function>lwres_buffer_back</function></funcdef> 132 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 133 <paramdef>unsigned int <parameter>n</parameter></paramdef> 134 </funcprototype> 135 136<funcprototype> 137 <funcdef> 138lwres_uint8_t 139<function>lwres_buffer_getuint8</function></funcdef> 140 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 141 </funcprototype> 142 143<funcprototype> 144 <funcdef> 145void 146<function>lwres_buffer_putuint8</function></funcdef> 147 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 148 <paramdef>lwres_uint8_t <parameter>val</parameter></paramdef> 149 </funcprototype> 150 151<funcprototype> 152 <funcdef> 153lwres_uint16_t 154<function>lwres_buffer_getuint16</function></funcdef> 155 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 156 </funcprototype> 157 158<funcprototype> 159 <funcdef> 160void 161<function>lwres_buffer_putuint16</function></funcdef> 162 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 163 <paramdef>lwres_uint16_t <parameter>val</parameter></paramdef> 164 </funcprototype> 165 166<funcprototype> 167 <funcdef> 168lwres_uint32_t 169<function>lwres_buffer_getuint32</function></funcdef> 170 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 171 </funcprototype> 172 173<funcprototype> 174 <funcdef> 175void 176<function>lwres_buffer_putuint32</function></funcdef> 177 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 178 <paramdef>lwres_uint32_t <parameter>val</parameter></paramdef> 179 </funcprototype> 180 181<funcprototype> 182 <funcdef> 183void 184<function>lwres_buffer_putmem</function></funcdef> 185 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 186 <paramdef>const unsigned char *<parameter>base</parameter></paramdef> 187 <paramdef>unsigned int <parameter>length</parameter></paramdef> 188 </funcprototype> 189 190<funcprototype> 191 <funcdef> 192void 193<function>lwres_buffer_getmem</function></funcdef> 194 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 195 <paramdef>unsigned char *<parameter>base</parameter></paramdef> 196 <paramdef>unsigned int <parameter>length</parameter></paramdef> 197 </funcprototype> 198 199</funcsynopsis> 200 </refsynopsisdiv> 201 202 <refsect1> 203 204 <title>DESCRIPTION</title> 205 <para> 206 These functions provide bounds checked access to a region of memory 207 where data is being read or written. 208 They are based on, and similar to, the 209 <literal>isc_buffer_</literal> 210 functions in the ISC library. 211 </para> 212 <para> 213 A buffer is a region of memory, together with a set of related 214 subregions. 215 The <emphasis>used region</emphasis> and the 216 <emphasis>available</emphasis> region are disjoint, and 217 their union is the buffer's region. 218 The used region extends from the beginning of the buffer region to the 219 last used byte. 220 The available region extends from one byte greater than the last used 221 byte to the end of the buffer's region. 222 The size of the used region can be changed using various 223 buffer commands. 224 Initially, the used region is empty. 225 </para> 226 <para> 227 The used region is further subdivided into two disjoint regions: the 228 <emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>. 229 The union of these two regions is the used region. 230 The consumed region extends from the beginning of the used region to 231 the byte before the <emphasis>current</emphasis> offset (if any). 232 The <emphasis>remaining</emphasis> region the current pointer to the end 233 of the used 234 region. 235 The size of the consumed region can be changed using various 236 buffer commands. 237 Initially, the consumed region is empty. 238 </para> 239 <para> 240 The <emphasis>active region</emphasis> is an (optional) subregion of the 241 remaining 242 region. 243 It extends from the current offset to an offset in the 244 remaining region. 245 Initially, the active region is empty. 246 If the current offset advances beyond the chosen offset, 247 the active region will also be empty. 248 </para> 249 <para><programlisting> 250 /------------entire length---------------\\ 251 /----- used region -----\\/-- available --\\ 252 +----------------------------------------+ 253 | consumed | remaining | | 254 +----------------------------------------+ 255 a b c d e 256 </programlisting> 257 </para> 258 <para><programlisting> 259 a == base of buffer. 260 b == current pointer. Can be anywhere between a and d. 261 c == active pointer. Meaningful between b and d. 262 d == used pointer. 263 e == length of buffer. 264 </programlisting> 265 </para> 266 <para><programlisting> 267 a-e == entire length of buffer. 268 a-d == used region. 269 a-b == consumed region. 270 b-d == remaining region. 271 b-c == optional active region. 272</programlisting> 273 </para> 274 <para><function>lwres_buffer_init()</function> 275 initializes the 276 <type>lwres_buffer_t</type> 277 <parameter>*b</parameter> 278 and assocates it with the memory region of size 279 <parameter>length</parameter> 280 bytes starting at location 281 <parameter>base.</parameter> 282 </para> 283 <para><function>lwres_buffer_invalidate()</function> 284 marks the buffer <parameter>*b</parameter> 285 as invalid. Invalidating a buffer after use is not required, 286 but makes it possible to catch its possible accidental use. 287 </para> 288 <para> 289 The functions 290 <function>lwres_buffer_add()</function> 291 and 292 <function>lwres_buffer_subtract()</function> 293 respectively increase and decrease the used space in 294 buffer 295 <parameter>*b</parameter> 296 by 297 <parameter>n</parameter> 298 bytes. 299 <function>lwres_buffer_add()</function> 300 checks for buffer overflow and 301 <function>lwres_buffer_subtract()</function> 302 checks for underflow. 303 These functions do not allocate or deallocate memory. 304 They just change the value of 305 <structfield>used</structfield>. 306 </para> 307 <para> 308 A buffer is re-initialised by 309 <function>lwres_buffer_clear()</function>. 310 The function sets 311 <structfield>used</structfield>, 312 <structfield>current</structfield> 313 and 314 <structfield>active</structfield> 315 to zero. 316 </para> 317 <para><function>lwres_buffer_first</function> 318 makes the consumed region of buffer 319 <parameter>*p</parameter> 320 empty by setting 321 <structfield>current</structfield> 322 to zero (the start of the buffer). 323 </para> 324 <para><function>lwres_buffer_forward()</function> 325 increases the consumed region of buffer 326 <parameter>*b</parameter> 327 by 328 <parameter>n</parameter> 329 bytes, checking for overflow. 330 Similarly, 331 <function>lwres_buffer_back()</function> 332 decreases buffer 333 <parameter>b</parameter>'s 334 consumed region by 335 <parameter>n</parameter> 336 bytes and checks for underflow. 337 </para> 338 <para><function>lwres_buffer_getuint8()</function> 339 reads an unsigned 8-bit integer from 340 <parameter>*b</parameter> 341 and returns it. 342 <function>lwres_buffer_putuint8()</function> 343 writes the unsigned 8-bit integer 344 <parameter>val</parameter> 345 to buffer 346 <parameter>*b</parameter>. 347 </para> 348 <para><function>lwres_buffer_getuint16()</function> 349 and 350 <function>lwres_buffer_getuint32()</function> 351 are identical to 352 <function>lwres_buffer_putuint8()</function> 353 except that they respectively read an unsigned 16-bit or 32-bit integer 354 in network byte order from 355 <parameter>b</parameter>. 356 Similarly, 357 <function>lwres_buffer_putuint16()</function> 358 and 359 <function>lwres_buffer_putuint32()</function> 360 writes the unsigned 16-bit or 32-bit integer 361 <parameter>val</parameter> 362 to buffer 363 <parameter>b</parameter>, 364 in network byte order. 365 </para> 366 <para> 367 Arbitrary amounts of data are read or written from a lightweight 368 resolver buffer with 369 <function>lwres_buffer_getmem()</function> 370 and 371 <function>lwres_buffer_putmem()</function> 372 respectively. 373 <function>lwres_buffer_putmem()</function> 374 copies 375 <parameter>length</parameter> 376 bytes of memory at 377 <parameter>base</parameter> 378 to 379 <parameter>b</parameter>. 380 Conversely, 381 <function>lwres_buffer_getmem()</function> 382 copies 383 <parameter>length</parameter> 384 bytes of memory from 385 <parameter>b</parameter> 386 to 387 <parameter>base</parameter>. 388 </para> 389 </refsect1> 390</refentry><!-- 391 - Local variables: 392 - mode: sgml 393 - End: 394--> 395