lwres_context (3)

NAME

       lwres_context_create,  lwres_context_destroy, lwres_context_nextserial,
       lwres_context_initserial,       lwres_context_freemem,       lwres_con-
       text_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_con-
       text_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 alloca-
       tion, 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_initse-
       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  send-
       base  -- 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 wait-
       ing for a response.

SEE ALSO

       lwres_conf_init(3), malloc(3), free(3).

BIND9                            Jun 30, 2000                 lwres_context(3)