lwres_context
LWRES_CONTEXT(3) LWRES_CONTEXT(3)
NAME
lwres_context_create, lwres_context_destroy, lwres_context_nextserial,
lwres_context_initserial, lwres_context_freemem, lwres_con-
text_allocmem, lwres_context_sendrecv - lightweight resolver context
management
SYNOPSIS
#include <lwres/lwres.h>
lwres_result_t lwres_context_create(lwres_context_t **contextp, void
*arg, lwres_malloc_t malloc_function, lwres_free_t free_function);
lwres_result_t lwres_context_destroy(lwres_context_t **contextp);
void lwres_context_initserial(lwres_context_t *ctx, lwres_uint32_t
serial);
lwres_uint32_t lwres_context_nextserial(lwres_context_t *ctx);
void lwres_context_freemem(lwres_context_t *ctx, void *mem, size_t
len);
void lwres_context_allocmem(lwres_context_t *ctx, size_t len);
void * lwres_context_sendrecv(lwres_context_t *ctx, void *sendbase,
int sendlen, void *recvbase, int recvlen, int *recvd_len);
DESCRIPTION
lwres_context_create() creates a lwres_context_t structure for use in
lightweight resolver operations. It holds a socket and other data
needed for communicating with a resolver daemon. The new lwres_con-
text_t is returned through contextp, a pointer to a lwres_context_t
pointer. This lwres_context_t pointer must initially be NULL, and is
modified to point to the newly created lwres_context_t.
When the lightweight resolver needs to perform dynamic memory alloca-
tion, it will call malloc_function to allocate memory and free_func-
tion to free it. If malloc_function and free_function are NULL, memory
is allocated using .Xr malloc 3 and free(3). It is not permitted to
have a NULL malloc_function and a non-NULL free_function or vice
versa. arg is passed as the first parameter to the memory allocation
functions. If malloc_function and free_function are NULL, arg is
unused and should be passed as NULL.
Once memory for the structure has been allocated, it is initialized
using lwres_conf_init(3) and returned via *contextp.
lwres_context_destroy() destroys a lwres_context_t, closing its
socket. contextp 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.
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 lwres_context_init-
serial() and lwres_context_nextserial(). lwres_context_initserial()
sets the serial number for context *ctx to serial. lwres_con-
text_nextserial() increments the serial number and returns the previ-
ous value.
Memory for a lightweight resolver context is allocated and freed using
lwres_context_allocmem() and lwres_context_freemem(). These use what-
ever allocations were defined when the context was created with
lwres_context_create(). lwres_context_allocmem() allocates len bytes
of memory and if successful returns a pointer to the allocated stor-
age. lwres_context_freemem() frees len bytes of space starting at
location mem.
lwres_context_sendrecv() performs I/O for the context ctx. Data are
read and written from the context’s socket. It writes data from send-
base — typically a lightweight resolver query packet — and waits for a
reply which is copied to the receive buffer at recvbase. The number
of bytes that were written to this receive buffer is returned in
*recvd_len.
RETURN VALUES
lwres_context_create() returns LWRES_R_NOMEMORY if memory for the
struct lwres_context could not be allocated, LWRES_R_SUCCESS other-
wise.
Successful calls to the memory allocator lwres_context_allocmem()
return a pointer to the start of the allocated space. It returns NULL
if memory could not be allocated.
LWRES_R_SUCCESS is returned when lwres_context_sendrecv() completes
successfully. LWRES_R_IOERROR is returned if an I/O error occurs and
LWRES_R_TIMEOUT is returned if lwres_context_sendrecv() times out
waiting for a response.
SEE ALSO
lwres_conf_init(3), malloc(3), free(3).
BIND9 Jun 30, 2000 LWRES_CONTEXT(3)
