1LWRES_CONTEXT(3) BIND9 LWRES_CONTEXT(3)
2
6 lwres_context_create, lwres_context_destroy, lwres_context_nextserial,
7 lwres_context_initserial, lwres_context_freemem,
8 lwres_context_allocmem, lwres_context_sendrecv - lightweight resolver
9 context management
10
12 #include <lwres/lwres.h>
13 lwres_result_t lwres_context_create(lwres_context_t **contextp,
15 void *arg,
16 lwres_malloc_t malloc_function,
17 lwres_free_t free_function);
18 lwres_result_t lwres_context_destroy(lwres_context_t **contextp);
20 void lwres_context_initserial(lwres_context_t *ctx, uint32_t serial);
22 uint32_t lwres_context_nextserial(lwres_context_t *ctx);
24 void lwres_context_freemem(lwres_context_t *ctx, void *mem,
26 size_t len);
27 void lwres_context_allocmem(lwres_context_t *ctx, size_t len);
29 void * lwres_context_sendrecv(lwres_context_t *ctx, void *sendbase,
31 int sendlen, void *recvbase, int recvlen,
32 int *recvd_len);
33
35 lwres_context_create() creates a lwres_context_t structure for use in
36 lightweight resolver operations. It holds a socket and other data
37 needed for communicating with a resolver daemon. The new
38 lwres_context_t is returned through contextp, a pointer to a
39 lwres_context_t pointer. This lwres_context_t pointer must initially be
40 NULL, and is modified to point to the newly created lwres_context_t.
41 When the lightweight resolver needs to perform dynamic memory
43 allocation, it will call malloc_function to allocate memory and
44 free_function to free it. If malloc_function and free_function are
45 NULL, memory is allocated using malloc(3). and free(3). It is not
46 permitted to have a NULL malloc_function and a non-NULL free_function
47 or vice versa. arg is passed as the first parameter to the memory
48 allocation functions. If malloc_function and free_function are NULL,
49 arg is unused and should be passed as NULL.
50 Once memory for the structure has been allocated, it is initialized
52 using lwres_conf_init(3) and returned via *contextp.
53 lwres_context_destroy() destroys a lwres_context_t, closing its socket.
55 contextp is a pointer to a pointer to the context that is to be
56 destroyed. The pointer will be set to NULL when the context has been
57 destroyed.
58 The context holds a serial number that is used to identify resolver
60 request packets and associate responses with the corresponding
61 requests. This serial number is controlled using
62 lwres_context_initserial() and lwres_context_nextserial().
63 lwres_context_initserial() sets the serial number for context *ctx to
64 serial. lwres_context_nextserial() increments the serial number and
65 returns the previous value.
66 Memory for a lightweight resolver context is allocated and freed using
68 lwres_context_allocmem() and lwres_context_freemem(). These use
69 whatever allocations were defined when the context was created with
70 lwres_context_create(). lwres_context_allocmem() allocates len bytes
71 of memory and if successful returns a pointer to the allocated storage.
72 lwres_context_freemem() frees len bytes of space starting at location
73 mem.
74 lwres_context_sendrecv() performs I/O for the context ctx. Data are
76 read and written from the context's socket. It writes data from
77 sendbase — typically a lightweight resolver query packet — and waits
78 for a reply which is copied to the receive buffer at recvbase. The
79 number of bytes that were written to this receive buffer is returned in
80 *recvd_len.
81
83 lwres_context_create() returns LWRES_R_NOMEMORY if memory for the
84 struct lwres_context could not be allocated, LWRES_R_SUCCESS otherwise.
85 Successful calls to the memory allocator lwres_context_allocmem()
87 return a pointer to the start of the allocated space. It returns NULL
88 if memory could not be allocated.
89 LWRES_R_SUCCESS is returned when lwres_context_sendrecv() completes
91 successfully. LWRES_R_IOERROR is returned if an I/O error occurs and
92 LWRES_R_TIMEOUT is returned if lwres_context_sendrecv() times out
93 waiting for a response.
94
96 lwres_conf_init(3), malloc(3), free(3).
97
99 Internet Systems Consortium, Inc.
100
102 Copyright © 2000, 2001, 2003-2005, 2007, 2014-2016, 2018-2020 Internet
103 Systems Consortium, Inc. ("ISC")
104ISC 2007-06-18 LWRES_CONTEXT(3)