Adding upstream version 1:9.11.5.P4+dfsg.upstream/1%9.11.5.P4+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 252 insertions, 0 deletions

diff --git a/lib/lwres/man/lwres_buffer.3 b/lib/lwres/man/lwres_buffer.3
new file mode 100644
index 0000000..f567132
--- /dev/null
+++ b/lib/lwres/man/lwres_buffer.3
@@ -0,0 +1,252 @@
+.\" Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016, 2018, 2019 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.78.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 assocates 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, 2019 Internet Systems Consortium, Inc. ("ISC")
+.br