Jun 30, 2000
lwres_context
3
BIND9
2004
2005
2007
2012
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` &mdash; typically a lightweight resolver query packet &mdash; 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 .