This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
t
Title: lwres_context
Author:
Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
Date: 2007-06-18
Manual: BIND9
Source: ISC
Language: English
* Define some portability stuff
-----------------------------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
http://bugs.debian.org/507673
http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------------------------------------
* set default formatting
-----------------------------------------------------------------
disable hyphenation
disable justification (adjust text to left margin only)
-----------------------------------------------------------------
* MAIN CONTENT STARTS HERE *
-----------------------------------------------------------------
#include <lwres/lwres.h>
\w'lwres_result_t lwres_context_create('u "lwres_result_t lwres_context_create(lwres_context_t **" "contextp" ", void *" "arg" ", lwres_malloc_t " "malloc_function" ", lwres_free_t " "free_function" ");"
\w'lwres_result_t lwres_context_destroy('u "lwres_result_t lwres_context_destroy(lwres_context_t **" "contextp" ");"
\w'void lwres_context_initserial('u "void lwres_context_initserial(lwres_context_t *" "ctx" ", lwres_uint32_t " "serial" ");"
\w'lwres_uint32_t lwres_context_nextserial('u "lwres_uint32_t lwres_context_nextserial(lwres_context_t *" "ctx" ");"
\w'void lwres_context_freemem('u "void lwres_context_freemem(lwres_context_t *" "ctx" ", void *" "mem" ", size_t " "len" ");"
\w'void lwres_context_allocmem('u "void lwres_context_allocmem(lwres_context_t *" "ctx" ", size_t " "len" ");"
\w'void * lwres_context_sendrecv('u "void * lwres_context_sendrecv(lwres_context_t *" "ctx" ", void *" "sendbase" ", int " "sendlen" ", void *" "recvbase" ", int " "recvlen" ", int *" "recvd_len" ");"
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\*(Aqs socket. It writes data from sendbase \(em typically a lightweight resolver query packet \(em 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.
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.
lwres_conf_init(3), malloc(3), free(3).
Internet Systems Consortium, Inc.
Copyright \(co 2000, 2001, 2003-2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")