1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
2 "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
3 [<!ENTITY mdash "—">]>
5 - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
6 - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
8 - Permission to use, copy, modify, and distribute this software for any
9 - purpose with or without fee is hereby granted, provided that the above
10 - copyright notice and this permission notice appear in all copies.
12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
18 - PERFORMANCE OF THIS SOFTWARE.
21 <!-- $Id: lwres_context.docbook,v 1.3.2.2.2.3 2005/05/12 21:36:12 sra Exp $ -->
27 <date>Jun 30, 2000</date>
30 <refentrytitle>lwres_context</refentrytitle>
31 <manvolnum>3</manvolnum>
32 <refmiscinfo>BIND9</refmiscinfo>
39 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
45 <holder>Internet Software Consortium.</holder>
50 <refname>lwres_context_create</refname>
51 <refname>lwres_context_destroy</refname>
52 <refname>lwres_context_nextserial</refname>
53 <refname>lwres_context_initserial</refname>
54 <refname>lwres_context_freemem</refname>
55 <refname>lwres_context_allocmem</refname>
56 <refname>lwres_context_sendrecv</refname>
57 <refpurpose>lightweight resolver context management</refpurpose>
61 <funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
65 <function>lwres_context_create</function></funcdef>
66 <paramdef>lwres_context_t **contextp</paramdef>
67 <paramdef>void *arg</paramdef>
68 <paramdef>lwres_malloc_t malloc_function</paramdef>
69 <paramdef>lwres_free_t free_function</paramdef>
74 <function>lwres_context_destroy</function></funcdef>
75 <paramdef>lwres_context_t **contextp</paramdef>
80 <function>lwres_context_initserial</function></funcdef>
81 <paramdef>lwres_context_t *ctx</paramdef>
82 <paramdef>lwres_uint32_t serial</paramdef>
87 <function>lwres_context_nextserial</function></funcdef>
88 <paramdef>lwres_context_t *ctx</paramdef>
93 <function>lwres_context_freemem</function></funcdef>
94 <paramdef>lwres_context_t *ctx</paramdef>
95 <paramdef>void *mem</paramdef>
96 <paramdef>size_t len</paramdef>
101 <function>lwres_context_allocmem</function></funcdef>
102 <paramdef>lwres_context_t *ctx</paramdef>
103 <paramdef>size_t len</paramdef>
108 <function>lwres_context_sendrecv</function></funcdef>
109 <paramdef>lwres_context_t *ctx</paramdef>
110 <paramdef>void *sendbase</paramdef>
111 <paramdef>int sendlen</paramdef>
112 <paramdef>void *recvbase</paramdef>
113 <paramdef>int recvlen</paramdef>
114 <paramdef>int *recvd_len</paramdef>
119 <title>DESCRIPTION</title>
121 <function>lwres_context_create()</function>
123 <type>lwres_context_t</type>
124 structure for use in lightweight resolver operations.
125 It holds a socket and other data needed for communicating
126 with a resolver daemon.
128 <type>lwres_context_t</type>
130 <parameter>contextp</parameter>,
133 <type>lwres_context_t</type>
135 <type>lwres_context_t</type>
136 pointer must initially be NULL, and is modified
137 to point to the newly created
138 <type>lwres_context_t</type>.
142 When the lightweight resolver needs to perform dynamic memory
143 allocation, it will call
144 <parameter>malloc_function</parameter>
145 to allocate memory and
146 <parameter>free_function</parameter>
149 <parameter>malloc_function</parameter>
151 <parameter>free_function</parameter>
153 are NULL, memory is allocated using
157 <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
160 It is not permitted to have a NULL
161 <parameter>malloc_function</parameter>
163 <parameter>free_function</parameter>
165 <parameter>arg</parameter>
166 is passed as the first parameter to the memory
167 allocation functions.
169 <parameter>malloc_function</parameter>
171 <parameter>free_function</parameter>
173 <parameter>arg</parameter>
175 is unused and should be passed as NULL.
178 Once memory for the structure has been allocated,
179 it is initialized using
181 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
185 <parameter>*contextp</parameter>.
189 <function>lwres_context_destroy()</function>
191 <type>lwres_context_t</type>,
194 <parameter>contextp</parameter>
195 is a pointer to a pointer to the context that is to be destroyed.
196 The pointer will be set to NULL when the context has been destroyed.
199 The context holds a serial number that is used to identify resolver
200 request packets and associate responses with the corresponding requests.
201 This serial number is controlled using
202 <function>lwres_context_initserial()</function>
204 <function>lwres_context_nextserial()</function>.
205 <function>lwres_context_initserial()</function>
206 sets the serial number for context
207 <parameter>*ctx</parameter>
209 <parameter>serial</parameter>.
211 <function>lwres_context_nextserial()</function>
212 increments the serial number and returns the previous value.
215 Memory for a lightweight resolver context is allocated and freed using
216 <function>lwres_context_allocmem()</function>
218 <function>lwres_context_freemem()</function>.
219 These use whatever allocations were defined when the context was
221 <function>lwres_context_create()</function>.
222 <function>lwres_context_allocmem()</function>
224 <parameter>len</parameter>
225 bytes of memory and if successful returns a pointer to the allocated
227 <function>lwres_context_freemem()</function>
229 <parameter>len</parameter>
230 bytes of space starting at location
231 <parameter>mem</parameter>.
235 <function>lwres_context_sendrecv()</function>
236 performs I/O for the context
237 <parameter>ctx</parameter>.
239 Data are read and written from the context's socket.
241 <parameter>sendbase</parameter>
242 — typically a lightweight resolver query packet —
243 and waits for a reply which is copied to the receive buffer at
244 <parameter>recvbase</parameter>.
246 The number of bytes that were written to this receive buffer is
248 <parameter>*recvd_len</parameter>.
253 <title>RETURN VALUES</title>
255 <function>lwres_context_create()</function>
257 <errorcode>LWRES_R_NOMEMORY</errorcode>
259 <type>struct lwres_context</type>
260 could not be allocated,
261 <errorcode>LWRES_R_SUCCESS</errorcode>
265 Successful calls to the memory allocator
266 <function>lwres_context_allocmem()</function>
267 return a pointer to the start of the allocated space.
268 It returns NULL if memory could not be allocated.
271 <errorcode>LWRES_R_SUCCESS</errorcode>
273 <function>lwres_context_sendrecv()</function>
274 completes successfully.
275 <errorcode>LWRES_R_IOERROR</errorcode>
276 is returned if an I/O error occurs and
277 <errorcode>LWRES_R_TIMEOUT</errorcode>
279 <function>lwres_context_sendrecv()</function>
280 times out waiting for a response.
284 <title>SEE ALSO</title>
287 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
291 <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
295 <refentrytitle>free</refentrytitle><manvolnum>3