1 files changed, 181 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_context.3 b/lib/lwres/man/lwres_context.3
new file mode 100644
index 0000000..13e09af
--- /dev/null
+++ b/lib/lwres/man/lwres_context.3
@@ -0,0 +1,181 @@
+.\" Copyright (C) 2000, 2001, 2003-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_context
+.\"    Author: 
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\"      Date: 2007-06-18
+.\"    Manual: BIND9
+.\"    Source: ISC
+.\"  Language: English
+.\"
+.TH "LWRES_CONTEXT" "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_context_create, lwres_context_destroy, lwres_context_nextserial, lwres_context_initserial, lwres_context_freemem, lwres_context_allocmem, lwres_context_sendrecv \- lightweight resolver context management
+.SH "SYNOPSIS"
+.sp
+.ft B
+.nf
+#include <lwres/lwres\&.h>
+.fi
+.ft
+.HP \w'lwres_result_t\ lwres_context_create('u
+.BI "lwres_result_t lwres_context_create(lwres_context_t\ **" "contextp" ", void\ *" "arg" ", lwres_malloc_t\ " "malloc_function" ", lwres_free_t\ " "free_function" ");"
+.HP \w'lwres_result_t\ lwres_context_destroy('u
+.BI "lwres_result_t lwres_context_destroy(lwres_context_t\ **" "contextp" ");"
+.HP \w'void\ lwres_context_initserial('u
+.BI "void lwres_context_initserial(lwres_context_t\ *" "ctx" ", uint32_t\ " "serial" ");"
+.HP \w'uint32_t\ lwres_context_nextserial('u
+.BI "uint32_t lwres_context_nextserial(lwres_context_t\ *" "ctx" ");"
+.HP \w'void\ lwres_context_freemem('u
+.BI "void lwres_context_freemem(lwres_context_t\ *" "ctx" ", void\ *" "mem" ", size_t\ " "len" ");"
+.HP \w'void\ lwres_context_allocmem('u
+.BI "void lwres_context_allocmem(lwres_context_t\ *" "ctx" ", size_t\ " "len" ");"
+.HP \w'void\ *\ lwres_context_sendrecv('u
+.BI "void * lwres_context_sendrecv(lwres_context_t\ *" "ctx" ", void\ *" "sendbase" ", int\ " "sendlen" ", void\ *" "recvbase" ", int\ " "recvlen" ", int\ *" "recvd_len" ");"
+.SH "DESCRIPTION"
+.PP
+\fBlwres_context_create()\fR
+creates a
+\fBlwres_context_t\fR
+structure for use in lightweight resolver operations\&. It holds a socket and other data needed for communicating with a resolver daemon\&. The new
+\fBlwres_context_t\fR
+is returned through
+\fIcontextp\fR, a pointer to a
+\fBlwres_context_t\fR
+pointer\&. This
+\fBlwres_context_t\fR
+pointer must initially be NULL, and is modified to point to the newly created
+\fBlwres_context_t\fR\&.
+.PP
+When the lightweight resolver needs to perform dynamic memory allocation, it will call
+\fImalloc_function\fR
+to allocate memory and
+\fIfree_function\fR
+to free it\&. If
+\fImalloc_function\fR
+and
+\fIfree_function\fR
+are NULL, memory is allocated using
+\fBmalloc\fR(3)\&. and
+\fBfree\fR(3)\&. It is not permitted to have a NULL
+\fImalloc_function\fR
+and a non\-NULL
+\fIfree_function\fR
+or vice versa\&.
+\fIarg\fR
+is passed as the first parameter to the memory allocation functions\&. If
+\fImalloc_function\fR
+and
+\fIfree_function\fR
+are NULL,
+\fIarg\fR
+is unused and should be passed as NULL\&.
+.PP
+Once memory for the structure has been allocated, it is initialized using
+\fBlwres_conf_init\fR(3)
+and returned via
+\fI*contextp\fR\&.
+.PP
+\fBlwres_context_destroy()\fR
+destroys a
+\fBlwres_context_t\fR, closing its socket\&.
+\fIcontextp\fR
+is a pointer to a pointer to the context that is to be destroyed\&. The pointer will be set to NULL when the context has been destroyed\&.
+.PP
+The context holds a serial number that is used to identify resolver request packets and associate responses with the corresponding requests\&. This serial number is controlled using
+\fBlwres_context_initserial()\fR
+and
+\fBlwres_context_nextserial()\fR\&.
+\fBlwres_context_initserial()\fR
+sets the serial number for context
+\fI*ctx\fR
+to
+\fIserial\fR\&.
+\fBlwres_context_nextserial()\fR
+increments the serial number and returns the previous value\&.
+.PP
+Memory for a lightweight resolver context is allocated and freed using
+\fBlwres_context_allocmem()\fR
+and
+\fBlwres_context_freemem()\fR\&. These use whatever allocations were defined when the context was created with
+\fBlwres_context_create()\fR\&.
+\fBlwres_context_allocmem()\fR
+allocates
+\fIlen\fR
+bytes of memory and if successful returns a pointer to the allocated storage\&.
+\fBlwres_context_freemem()\fR
+frees
+\fIlen\fR
+bytes of space starting at location
+\fImem\fR\&.
+.PP
+\fBlwres_context_sendrecv()\fR
+performs I/O for the context
+\fIctx\fR\&. Data are read and written from the context\*(Aqs socket\&. It writes data from
+\fIsendbase\fR
+\(em typically a lightweight resolver query packet \(em and waits for a reply which is copied to the receive buffer at
+\fIrecvbase\fR\&. The number of bytes that were written to this receive buffer is returned in
+\fI*recvd_len\fR\&.
+.SH "RETURN VALUES"
+.PP
+\fBlwres_context_create()\fR
+returns
+\fBLWRES_R_NOMEMORY\fR
+if memory for the
+\fBstruct lwres_context\fR
+could not be allocated,
+\fBLWRES_R_SUCCESS\fR
+otherwise\&.
+.PP
+Successful calls to the memory allocator
+\fBlwres_context_allocmem()\fR
+return a pointer to the start of the allocated space\&. It returns NULL if memory could not be allocated\&.
+.PP
+\fBLWRES_R_SUCCESS\fR
+is returned when
+\fBlwres_context_sendrecv()\fR
+completes successfully\&.
+\fBLWRES_R_IOERROR\fR
+is returned if an I/O error occurs and
+\fBLWRES_R_TIMEOUT\fR
+is returned if
+\fBlwres_context_sendrecv()\fR
+times out waiting for a response\&.
+.SH "SEE ALSO"
+.PP
+\fBlwres_conf_init\fR(3),
+\fBmalloc\fR(3),
+\fBfree\fR(3)\&.
+.SH "AUTHOR"
+.PP
+\fBInternet Systems Consortium, Inc\&.\fR
+.SH "COPYRIGHT"
+.br
+Copyright \(co 2000, 2001, 2003-2005, 2007, 2014-2016, 2018, 2019 Internet Systems Consortium, Inc. ("ISC")
+.br