Index for Section 3

Alphabetical listing for L

Bottom of page

LWRES_CONTEXT(3)
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 .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 ).

Index for Section 3

Alphabetical listing for L

Top of page