Jun 30, 2000
lwres_context
3
BIND9

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