diff options
Diffstat (limited to 'lib/lwres/man/lwres_context.3')
| -rw-r--r-- | lib/lwres/man/lwres_context.3 | 181 |
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 |