June 18, 2007
lwres_context 3 BIND9
2004 2005 2007 2014 Internet Systems Consortium, Inc. ("ISC")
2000 2001 2003 Internet Software Consortium.
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

    #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_context_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 allocation, it will call malloc_function to allocate memory and free_function to free it. If malloc_function and free_function are NULL, memory is allocated using 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_initserial()` and `lwres_context_nextserial()`. `lwres_context_initserial()` sets the serial number for context *ctx to serial. `lwres_context_nextserial()` increments the serial number and returns the previous value.

Memory for a lightweight resolver context is allocated and freed using `lwres_context_allocmem()` and `lwres_context_freemem()`. These use whatever 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 storage. `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 sendbase — 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 otherwise.

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 .