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 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) .