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

AUTHOR

       Internet Systems Consortium, Inc.

COPYRIGHT

       Copyright © 2000, 2001, 2003-2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")