diff options
Diffstat (limited to 'lib/liblwres/man/lwres_context.3')
| -rw-r--r-- | lib/liblwres/man/lwres_context.3 | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/lib/liblwres/man/lwres_context.3 b/lib/liblwres/man/lwres_context.3 new file mode 100644 index 000000000..d55c14fef --- /dev/null +++ b/lib/liblwres/man/lwres_context.3 @@ -0,0 +1,194 @@ +.\" +.\" Copyright (C) 2000, 2001 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.TH "LWRES_CONTEXT" "3" "Jun 30, 2000" "BIND9" "" +.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 +\fB#include <lwres/lwres.h> +.sp +.na +lwres_result_t +lwres_context_create(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, lwres_free_t free_function); +.ad +.sp +.na +lwres_result_t +lwres_context_destroy(lwres_context_t **contextp); +.ad +.sp +.na +void +lwres_context_initserial(lwres_context_t *ctx, lwres_uint32_t serial); +.ad +.sp +.na +lwres_uint32_t +lwres_context_nextserial(lwres_context_t *ctx); +.ad +.sp +.na +void +lwres_context_freemem(lwres_context_t *ctx, void *mem, size_t len); +.ad +.sp +.na +void +lwres_context_allocmem(lwres_context_t *ctx, size_t len); +.ad +.sp +.na +void * +lwres_context_sendrecv(lwres_context_t *ctx, void *sendbase, int sendlen, void *recvbase, int recvlen, int *recvd_len); +.ad +\fR.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 throught +\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 +\&.Xr malloc 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's 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 +LWRES_R_NOMEMORY +if memory for the +\fBstruct lwres_context\fR +could not be allocated, +LWRES_R_SUCCESS +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 +LWRES_R_SUCCESS +is returned when +\fBlwres_context_sendrecv()\fR +completes successfully. +LWRES_R_IOERROR +is returned if an I/O error occurs and +LWRES_R_TIMEOUT +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). |