1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3 [<!ENTITY mdash "—">]>
5 - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
6 - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
8 - Permission to use, copy, modify, and/or 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.6 2007/08/28 07:19:18 tbox Exp $ -->
27 <date>Jun 30, 2000</date>
30 <refentrytitle>lwres_context</refentrytitle>
31 <manvolnum>3</manvolnum>
32 <refmiscinfo>BIND9</refmiscinfo>
40 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
46 <holder>Internet Software Consortium.</holder>
51 <refname>lwres_context_create</refname>
52 <refname>lwres_context_destroy</refname>
53 <refname>lwres_context_nextserial</refname>
54 <refname>lwres_context_initserial</refname>
55 <refname>lwres_context_freemem</refname>
56 <refname>lwres_context_allocmem</refname>
57 <refname>lwres_context_sendrecv</refname>
58 <refpurpose>lightweight resolver context management</refpurpose>
62 <funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
66 <function>lwres_context_create</function></funcdef>
67 <paramdef>lwres_context_t **contextp</paramdef>
68 <paramdef>void *arg</paramdef>
69 <paramdef>lwres_malloc_t malloc_function</paramdef>
70 <paramdef>lwres_free_t free_function</paramdef>
75 <function>lwres_context_destroy</function></funcdef>
76 <paramdef>lwres_context_t **contextp</paramdef>
81 <function>lwres_context_initserial</function></funcdef>
82 <paramdef>lwres_context_t *ctx</paramdef>
83 <paramdef>lwres_uint32_t serial</paramdef>
88 <function>lwres_context_nextserial</function></funcdef>
89 <paramdef>lwres_context_t *ctx</paramdef>
94 <function>lwres_context_freemem</function></funcdef>
95 <paramdef>lwres_context_t *ctx</paramdef>
96 <paramdef>void *mem</paramdef>
97 <paramdef>size_t len</paramdef>
102 <function>lwres_context_allocmem</function></funcdef>
103 <paramdef>lwres_context_t *ctx</paramdef>
104 <paramdef>size_t len</paramdef>
109 <function>lwres_context_sendrecv</function></funcdef>
110 <paramdef>lwres_context_t *ctx</paramdef>
111 <paramdef>void *sendbase</paramdef>
112 <paramdef>int sendlen</paramdef>
113 <paramdef>void *recvbase</paramdef>
114 <paramdef>int recvlen</paramdef>
115 <paramdef>int *recvd_len</paramdef>
120 <title>DESCRIPTION</title>
122 <function>lwres_context_create()</function>
124 <type>lwres_context_t</type>
125 structure for use in lightweight resolver operations.
126 It holds a socket and other data needed for communicating
127 with a resolver daemon.
129 <type>lwres_context_t</type>
131 <parameter>contextp</parameter>,
134 <type>lwres_context_t</type>
136 <type>lwres_context_t</type>
137 pointer must initially be NULL, and is modified
138 to point to the newly created
139 <type>lwres_context_t</type>.
143 When the lightweight resolver needs to perform dynamic memory
144 allocation, it will call
145 <parameter>malloc_function</parameter>
146 to allocate memory and
147 <parameter>free_function</parameter>
150 <parameter>malloc_function</parameter>
152 <parameter>free_function</parameter>
154 are NULL, memory is allocated using
158 <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
161 It is not permitted to have a NULL
162 <parameter>malloc_function</parameter>
164 <parameter>free_function</parameter>
166 <parameter>arg</parameter>
167 is passed as the first parameter to the memory
168 allocation functions.
170 <parameter>malloc_function</parameter>
172 <parameter>free_function</parameter>
174 <parameter>arg</parameter>
176 is unused and should be passed as NULL.
179 Once memory for the structure has been allocated,
180 it is initialized using
182 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
186 <parameter>*contextp</parameter>.
190 <function>lwres_context_destroy()</function>
192 <type>lwres_context_t</type>,
195 <parameter>contextp</parameter>
196 is a pointer to a pointer to the context that is to be destroyed.
197 The pointer will be set to NULL when the context has been destroyed.
200 The context holds a serial number that is used to identify resolver
201 request packets and associate responses with the corresponding requests.
202 This serial number is controlled using
203 <function>lwres_context_initserial()</function>
205 <function>lwres_context_nextserial()</function>.
206 <function>lwres_context_initserial()</function>
207 sets the serial number for context
208 <parameter>*ctx</parameter>
210 <parameter>serial</parameter>.
212 <function>lwres_context_nextserial()</function>
213 increments the serial number and returns the previous value.
216 Memory for a lightweight resolver context is allocated and freed using
217 <function>lwres_context_allocmem()</function>
219 <function>lwres_context_freemem()</function>.
220 These use whatever allocations were defined when the context was
222 <function>lwres_context_create()</function>.
223 <function>lwres_context_allocmem()</function>
225 <parameter>len</parameter>
226 bytes of memory and if successful returns a pointer to the allocated
228 <function>lwres_context_freemem()</function>
230 <parameter>len</parameter>
231 bytes of space starting at location
232 <parameter>mem</parameter>.
236 <function>lwres_context_sendrecv()</function>
237 performs I/O for the context
238 <parameter>ctx</parameter>.
240 Data are read and written from the context's socket.
242 <parameter>sendbase</parameter>
243 — typically a lightweight resolver query packet —
244 and waits for a reply which is copied to the receive buffer at
245 <parameter>recvbase</parameter>.
247 The number of bytes that were written to this receive buffer is
249 <parameter>*recvd_len</parameter>.
254 <title>RETURN VALUES</title>
256 <function>lwres_context_create()</function>
258 <errorcode>LWRES_R_NOMEMORY</errorcode>
260 <type>struct lwres_context</type>
261 could not be allocated,
262 <errorcode>LWRES_R_SUCCESS</errorcode>
266 Successful calls to the memory allocator
267 <function>lwres_context_allocmem()</function>
268 return a pointer to the start of the allocated space.
269 It returns NULL if memory could not be allocated.
272 <errorcode>LWRES_R_SUCCESS</errorcode>
274 <function>lwres_context_sendrecv()</function>
275 completes successfully.
276 <errorcode>LWRES_R_IOERROR</errorcode>
277 is returned if an I/O error occurs and
278 <errorcode>LWRES_R_TIMEOUT</errorcode>
280 <function>lwres_context_sendrecv()</function>
281 times out waiting for a response.
285 <title>SEE ALSO</title>
288 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
292 <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
296 <refentrytitle>free</refentrytitle><manvolnum>3