1LWRES_CONTEXT(3)                     BIND9                    LWRES_CONTEXT(3)
2
3
4

NAME

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

SYNOPSIS

12       #include <lwres/lwres.h>
13
14       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
19       lwres_result_t lwres_context_destroy(lwres_context_t **contextp);
20
21       void lwres_context_initserial(lwres_context_t *ctx,
22                                     lwres_uint32_t serial);
23
24       lwres_uint32_t lwres_context_nextserial(lwres_context_t *ctx);
25
26       void lwres_context_freemem(lwres_context_t *ctx, void *mem,
27                                  size_t len);
28
29       void lwres_context_allocmem(lwres_context_t *ctx, size_t len);
30
31       void * lwres_context_sendrecv(lwres_context_t *ctx, void *sendbase,
32                                     int sendlen, void *recvbase, int recvlen,
33                                     int *recvd_len);
34

DESCRIPTION

36       lwres_context_create() creates a lwres_context_t structure for use in
37       lightweight resolver operations. It holds a socket and other data
38       needed for communicating with a resolver daemon. The new
39       lwres_context_t is returned through contextp, a pointer to a
40       lwres_context_t pointer. This lwres_context_t pointer must initially be
41       NULL, and is modified to point to the newly created lwres_context_t.
42
43       When the lightweight resolver needs to perform dynamic memory
44       allocation, it will call malloc_function to allocate memory and
45       free_function to free it. If malloc_function and free_function are
46       NULL, memory is allocated using malloc(3). and free(3). It is not
47       permitted to have a NULL malloc_function and a non-NULL free_function
48       or vice versa.  arg is passed as the first parameter to the memory
49       allocation functions. If malloc_function and free_function are NULL,
50       arg is unused and should be passed as NULL.
51
52       Once memory for the structure has been allocated, it is initialized
53       using lwres_conf_init(3) and returned via *contextp.
54
55       lwres_context_destroy() destroys a lwres_context_t, closing its socket.
56       contextp is a pointer to a pointer to the context that is to be
57       destroyed. The pointer will be set to NULL when the context has been
58       destroyed.
59
60       The context holds a serial number that is used to identify resolver
61       request packets and associate responses with the corresponding
62       requests. This serial number is controlled using
63       lwres_context_initserial() and lwres_context_nextserial().
64       lwres_context_initserial() sets the serial number for context *ctx to
65       serial.  lwres_context_nextserial() increments the serial number and
66       returns the previous value.
67
68       Memory for a lightweight resolver context is allocated and freed using
69       lwres_context_allocmem() and lwres_context_freemem(). These use
70       whatever allocations were defined when the context was created with
71       lwres_context_create().  lwres_context_allocmem() allocates len bytes
72       of memory and if successful returns a pointer to the allocated storage.
73       lwres_context_freemem() frees len bytes of space starting at location
74       mem.
75
76       lwres_context_sendrecv() performs I/O for the context ctx. Data are
77       read and written from the context's socket. It writes data from
78       sendbase — typically a lightweight resolver query packet — and waits
79       for a reply which is copied to the receive buffer at recvbase. The
80       number of bytes that were written to this receive buffer is returned in
81       *recvd_len.
82

RETURN VALUES

84       lwres_context_create() returns LWRES_R_NOMEMORY if memory for the
85       struct lwres_context could not be allocated, LWRES_R_SUCCESS otherwise.
86
87       Successful calls to the memory allocator lwres_context_allocmem()
88       return a pointer to the start of the allocated space. It returns NULL
89       if memory could not be allocated.
90
91       LWRES_R_SUCCESS is returned when lwres_context_sendrecv() completes
92       successfully.  LWRES_R_IOERROR is returned if an I/O error occurs and
93       LWRES_R_TIMEOUT is returned if lwres_context_sendrecv() times out
94       waiting for a response.
95

SEE ALSO

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

AUTHOR

100       Internet Systems Consortium, Inc.
101
103       Copyright © 2000, 2001, 2003-2005, 2007, 2014-2016, 2018 Internet
104       Systems Consortium, Inc. ("ISC")
105
106
107
108ISC                               2007-06-18                  LWRES_CONTEXT(3)
Impressum