lwres_context

+ + + + + + + +

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`,
	uint32_t `serial)`;

+ + + +

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

Name

Synopsis

DESCRIPTION

RETURN VALUES

SEE ALSO