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, 176 insertions, 0 deletions

diff --git a/lib/lwres/man/lwres.3 b/lib/lwres/man/lwres.3
new file mode 100644
index 0000000..61bed07
--- /dev/null
+++ b/lib/lwres/man/lwres.3
@@ -0,0 +1,176 @@
+.\" 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
+.\"    Author: 
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\"      Date: 2007-06-18
+.\"    Manual: BIND9
+.\"    Source: ISC
+.\"  Language: English
+.\"
+.TH "LWRES" "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 \- introduction to the lightweight resolver library
+.SH "SYNOPSIS"
+.sp
+.ft B
+.nf
+#include <lwres/lwres\&.h>
+.fi
+.ft
+.SH "DESCRIPTION"
+.PP
+The BIND 9 lightweight resolver library is a simple, name service independent stub resolver library\&. It provides hostname\-to\-address and address\-to\-hostname lookup services to applications by transmitting lookup requests to a resolver daemon
+\fBlwresd\fR
+running on the local host\&. The resolver daemon performs the lookup using the DNS or possibly other name service protocols, and returns the results to the application through the library\&. The library and resolver daemon communicate using a simple UDP\-based protocol\&.
+.SH "OVERVIEW"
+.PP
+The lwresd library implements multiple name service APIs\&. The standard
+\fBgethostbyname()\fR,
+\fBgethostbyaddr()\fR,
+\fBgethostbyname_r()\fR,
+\fBgethostbyaddr_r()\fR,
+\fBgetaddrinfo()\fR,
+\fBgetipnodebyname()\fR, and
+\fBgetipnodebyaddr()\fR
+functions are all supported\&. To allow the lwres library to coexist with system libraries that define functions of the same name, the library defines these functions with names prefixed by
+lwres_\&. To define the standard names, applications must include the header file
+<lwres/netdb\&.h>
+which contains macro definitions mapping the standard function names into
+lwres_
+prefixed ones\&. Operating system vendors who integrate the lwres library into their base distributions should rename the functions in the library proper so that the renaming macros are not needed\&.
+.PP
+The library also provides a native API consisting of the functions
+\fBlwres_getaddrsbyname()\fR
+and
+\fBlwres_getnamebyaddr()\fR\&. These may be called by applications that require more detailed control over the lookup process than the standard functions provide\&.
+.PP
+In addition to these name service independent address lookup functions, the library implements a new, experimental API for looking up arbitrary DNS resource records, using the
+\fBlwres_getaddrsbyname()\fR
+function\&.
+.PP
+Finally, there is a low\-level API for converting lookup requests and responses to and from raw lwres protocol packets\&. This API can be used by clients requiring nonblocking operation, and is also used when implementing the server side of the lwres protocol, for example in the
+\fBlwresd\fR
+resolver daemon\&. The use of this low\-level API in clients and servers is outlined in the following sections\&.
+.SH "CLIENT-SIDE LOW-LEVEL API CALL FLOW"
+.PP
+When a client program wishes to make an lwres request using the native low\-level API, it typically performs the following sequence of actions\&.
+.PP
+(1) Allocate or use an existing
+\fBlwres_packet_t\fR, called
+\fIpkt\fR
+below\&.
+.PP
+(2) Set
+\fIpkt\&.recvlength\fR
+to the maximum length we will accept\&. This is done so the receiver of our packets knows how large our receive buffer is\&. The "default" is a constant in
+lwres\&.h:
+\fBLWRES_RECVLENGTH = 4096\fR\&.
+.PP
+(3) Set
+\fIpkt\&.serial\fR
+to a unique serial number\&. This value is echoed back to the application by the remote server\&.
+.PP
+(4) Set
+\fIpkt\&.pktflags\fR\&. Usually this is set to 0\&.
+.PP
+(5) Set
+\fIpkt\&.result\fR
+to 0\&.
+.PP
+(6) Call
+\fBlwres_*request_render()\fR, or marshall in the data using the primitives such as
+\fBlwres_packet_render()\fR
+and storing the packet data\&.
+.PP
+(7) Transmit the resulting buffer\&.
+.PP
+(8) Call
+\fBlwres_*response_parse()\fR
+to parse any packets received\&.
+.PP
+(9) Verify that the opcode and serial match a request, and process the packet specific information contained in the body\&.
+.SH "SERVER-SIDE LOW-LEVEL API CALL FLOW"
+.PP
+When implementing the server side of the lightweight resolver protocol using the lwres library, a sequence of actions like the following is typically involved in processing each request packet\&.
+.PP
+Note that the same
+\fBlwres_packet_t\fR
+is used in both the
+\fB_parse()\fR
+and
+\fB_render()\fR
+calls, with only a few modifications made to the packet header\*(Aqs contents between uses\&. This method is recommended as it keeps the serial, opcode, and other fields correct\&.
+.PP
+(1) When a packet is received, call
+\fBlwres_*request_parse()\fR
+to unmarshall it\&. This returns a
+\fBlwres_packet_t\fR
+(also called
+\fIpkt\fR, below) as well as a data specific type, such as
+\fBlwres_gabnrequest_t\fR\&.
+.PP
+(2) Process the request in the data specific type\&.
+.PP
+(3) Set the
+\fIpkt\&.result\fR,
+\fIpkt\&.recvlength\fR
+as above\&. All other fields can be left untouched since they were filled in by the
+\fB*_parse()\fR
+call above\&. If using
+\fBlwres_*response_render()\fR,
+\fIpkt\&.pktflags\fR
+will be set up properly\&. Otherwise, the
+\fBLWRES_LWPACKETFLAG_RESPONSE\fR
+bit should be set\&.
+.PP
+(4) Call the data specific rendering function, such as
+\fBlwres_gabnresponse_render()\fR\&.
+.PP
+(5) Send the resulting packet to the client\&.
+.PP
+.SH "SEE ALSO"
+.PP
+\fBlwres_gethostent\fR(3),
+\fBlwres_getipnode\fR(3),
+\fBlwres_getnameinfo\fR(3),
+\fBlwres_noop\fR(3),
+\fBlwres_gabn\fR(3),
+\fBlwres_gnba\fR(3),
+\fBlwres_context\fR(3),
+\fBlwres_config\fR(3),
+\fBresolver\fR(5),
+\fBlwresd\fR(8)\&.
+.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