# lwres_context

## 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

## 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_context_t is returned throught `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 .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_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).