.\" Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016, 2018-2020 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/.
.\"
.hy 0
.ad l
'\" t
.\"     Title: lwres_buffer
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 2007-06-18
.\"    Manual: BIND9
.\"    Source: ISC
.\"  Language: English
.\"
.TH "LWRES_BUFFER" "3" "2007\-06\-18" "ISC" "BIND9"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
lwres_buffer_init, lwres_buffer_invalidate, lwres_buffer_add, lwres_buffer_subtract, lwres_buffer_clear, lwres_buffer_first, lwres_buffer_forward, lwres_buffer_back, lwres_buffer_getuint8, lwres_buffer_putuint8, lwres_buffer_getuint16, lwres_buffer_putuint16, lwres_buffer_getuint32, lwres_buffer_putuint32, lwres_buffer_putmem, lwres_buffer_getmem \- lightweight resolver buffer management
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <lwres/lwbuffer\&.h>
.fi
.ft
.HP \w'void\ lwres_buffer_init('u
.BI "void lwres_buffer_init(lwres_buffer_t\ *" "b" ", void\ *" "base" ", unsigned\ int\ " "length" ");"
.HP \w'void\ lwres_buffer_invalidate('u
.BI "void lwres_buffer_invalidate(lwres_buffer_t\ *" "b" ");"
.HP \w'void\ lwres_buffer_add('u
.BI "void lwres_buffer_add(lwres_buffer_t\ *" "b" ", unsigned\ int\ " "n" ");"
.HP \w'void\ lwres_buffer_subtract('u
.BI "void lwres_buffer_subtract(lwres_buffer_t\ *" "b" ", unsigned\ int\ " "n" ");"
.HP \w'void\ lwres_buffer_clear('u
.BI "void lwres_buffer_clear(lwres_buffer_t\ *" "b" ");"
.HP \w'void\ lwres_buffer_first('u
.BI "void lwres_buffer_first(lwres_buffer_t\ *" "b" ");"
.HP \w'void\ lwres_buffer_forward('u
.BI "void lwres_buffer_forward(lwres_buffer_t\ *" "b" ", unsigned\ int\ " "n" ");"
.HP \w'void\ lwres_buffer_back('u
.BI "void lwres_buffer_back(lwres_buffer_t\ *" "b" ", unsigned\ int\ " "n" ");"
.HP \w'uint8_t\ lwres_buffer_getuint8('u
.BI "uint8_t lwres_buffer_getuint8(lwres_buffer_t\ *" "b" ");"
.HP \w'void\ lwres_buffer_putuint8('u
.BI "void lwres_buffer_putuint8(lwres_buffer_t\ *" "b" ", uint8_t\ " "val" ");"
.HP \w'uint16_t\ lwres_buffer_getuint16('u
.BI "uint16_t lwres_buffer_getuint16(lwres_buffer_t\ *" "b" ");"
.HP \w'void\ lwres_buffer_putuint16('u
.BI "void lwres_buffer_putuint16(lwres_buffer_t\ *" "b" ", uint16_t\ " "val" ");"
.HP \w'uint32_t\ lwres_buffer_getuint32('u
.BI "uint32_t lwres_buffer_getuint32(lwres_buffer_t\ *" "b" ");"
.HP \w'void\ lwres_buffer_putuint32('u
.BI "void lwres_buffer_putuint32(lwres_buffer_t\ *" "b" ", uint32_t\ " "val" ");"
.HP \w'void\ lwres_buffer_putmem('u
.BI "void lwres_buffer_putmem(lwres_buffer_t\ *" "b" ", const\ unsigned\ char\ *" "base" ", unsigned\ int\ " "length" ");"
.HP \w'void\ lwres_buffer_getmem('u
.BI "void lwres_buffer_getmem(lwres_buffer_t\ *" "b" ", unsigned\ char\ *" "base" ", unsigned\ int\ " "length" ");"
.SH "DESCRIPTION"
.PP
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
isc_buffer_
functions in the ISC library\&.
.PP
A buffer is a region of memory, together with a set of related subregions\&. The
\fIused region\fR
and the
\fIavailable\fR
region are disjoint, and their union is the buffer\*(Aqs 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\*(Aqs region\&. The size of the used region can be changed using various buffer commands\&. Initially, the used region is empty\&.
.PP
The used region is further subdivided into two disjoint regions: the
\fIconsumed region\fR
and the
\fIremaining region\fR\&. 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
\fIcurrent\fR
offset (if any)\&. The
\fIremaining\fR
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\&.
.PP
The
\fIactive region\fR
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\&.
.PP
.if n \{\
.RS 4
.\}
.nf
   /\-\-\-\-\-\-\-\-\-\-\-\-entire length\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\e\e
   /\-\-\-\-\- used region \-\-\-\-\-\e\e/\-\- available \-\-\e\e
   +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
   | consumed  | remaining |                |
   +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
   a           b     c     d                e
.fi
.if n \{\
.RE
.\}
.PP
.if n \{\
.RS 4
.\}
.nf
  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\&.
.fi
.if n \{\
.RE
.\}
.PP
.if n \{\
.RS 4
.\}
.nf
  a\-e == entire length of buffer\&.
  a\-d == used region\&.
  a\-b == consumed region\&.
  b\-d == remaining region\&.
  b\-c == optional active region\&.
.fi
.if n \{\
.RE
.\}
.PP
\fBlwres_buffer_init()\fR
initializes the
\fBlwres_buffer_t\fR
\fI*b\fR
and associates it with the memory region of size
\fIlength\fR
bytes starting at location
\fIbase\&.\fR
.PP
\fBlwres_buffer_invalidate()\fR
marks the buffer
\fI*b\fR
as invalid\&. Invalidating a buffer after use is not required, but makes it possible to catch its possible accidental use\&.
.PP
The functions
\fBlwres_buffer_add()\fR
and
\fBlwres_buffer_subtract()\fR
respectively increase and decrease the used space in buffer
\fI*b\fR
by
\fIn\fR
bytes\&.
\fBlwres_buffer_add()\fR
checks for buffer overflow and
\fBlwres_buffer_subtract()\fR
checks for underflow\&. These functions do not allocate or deallocate memory\&. They just change the value of
\fIused\fR\&.
.PP
A buffer is re\-initialised by
\fBlwres_buffer_clear()\fR\&. The function sets
\fIused\fR,
\fIcurrent\fR
and
\fIactive\fR
to zero\&.
.PP
\fBlwres_buffer_first\fR
makes the consumed region of buffer
\fI*p\fR
empty by setting
\fIcurrent\fR
to zero (the start of the buffer)\&.
.PP
\fBlwres_buffer_forward()\fR
increases the consumed region of buffer
\fI*b\fR
by
\fIn\fR
bytes, checking for overflow\&. Similarly,
\fBlwres_buffer_back()\fR
decreases buffer
\fIb\fR\*(Aqs consumed region by
\fIn\fR
bytes and checks for underflow\&.
.PP
\fBlwres_buffer_getuint8()\fR
reads an unsigned 8\-bit integer from
\fI*b\fR
and returns it\&.
\fBlwres_buffer_putuint8()\fR
writes the unsigned 8\-bit integer
\fIval\fR
to buffer
\fI*b\fR\&.
.PP
\fBlwres_buffer_getuint16()\fR
and
\fBlwres_buffer_getuint32()\fR
are identical to
\fBlwres_buffer_putuint8()\fR
except that they respectively read an unsigned 16\-bit or 32\-bit integer in network byte order from
\fIb\fR\&. Similarly,
\fBlwres_buffer_putuint16()\fR
and
\fBlwres_buffer_putuint32()\fR
writes the unsigned 16\-bit or 32\-bit integer
\fIval\fR
to buffer
\fIb\fR, in network byte order\&.
.PP
Arbitrary amounts of data are read or written from a lightweight resolver buffer with
\fBlwres_buffer_getmem()\fR
and
\fBlwres_buffer_putmem()\fR
respectively\&.
\fBlwres_buffer_putmem()\fR
copies
\fIlength\fR
bytes of memory at
\fIbase\fR
to
\fIb\fR\&. Conversely,
\fBlwres_buffer_getmem()\fR
copies
\fIlength\fR
bytes of memory from
\fIb\fR
to
\fIbase\fR\&.
.SH "AUTHOR"
.PP
\fBInternet Systems Consortium, Inc\&.\fR
.SH "COPYRIGHT"
.br
Copyright \(co 2000, 2001, 2004, 2005, 2007, 2014-2016, 2018-2020 Internet Systems Consortium, Inc. ("ISC")
.br