2 - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
3 - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
5 - Permission to use, copy, modify, and distribute this software for any
6 - purpose with or without fee is hereby granted, provided that the above
7 - copyright notice and this permission notice appear in all copies.
9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 - PERFORMANCE OF THIS SOFTWARE.
17 <!-- $Id: lwres_context.html,v 1.5.2.2.2.12 2006/06/29 13:02:31 marka Exp $ -->
20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
21 <title>lwres_context</title>
22 <meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="id2482688"></a><div class="titlepage"></div>
26 <div class="refnamediv">
28 <p>lwres_context_create, lwres_context_destroy, lwres_context_nextserial, lwres_context_initserial, lwres_context_freemem, lwres_context_allocmem, lwres_context_sendrecv — lightweight resolver context management</p>
30 <div class="refsynopsisdiv">
32 <div class="funcsynopsis">
33 <pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
34 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
36 <td><code class="funcdef">
38 <b class="fsfunc">lwres_context_create</b>(</code></td>
64 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
66 <td><code class="funcdef">
68 <b class="fsfunc">lwres_context_destroy</b>(</code></td>
80 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
82 <td><code class="funcdef">
84 <b class="fsfunc">lwres_context_initserial</b>(</code></td>
100 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
102 <td><code class="funcdef">
104 <b class="fsfunc">lwres_context_nextserial</b>(</code></td>
116 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
118 <td><code class="funcdef">
120 <b class="fsfunc">lwres_context_freemem</b>(</code></td>
141 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
143 <td><code class="funcdef">
145 <b class="fsfunc">lwres_context_allocmem</b>(</code></td>
161 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
163 <td><code class="funcdef">
165 <b class="fsfunc">lwres_context_sendrecv</b>(</code></td>
203 <div class="refsect1" lang="en">
204 <a name="id2549540"></a><h2>DESCRIPTION</h2>
206 <code class="function">lwres_context_create()</code>
208 <span class="type">lwres_context_t</span>
209 structure for use in lightweight resolver operations.
210 It holds a socket and other data needed for communicating
211 with a resolver daemon.
213 <span class="type">lwres_context_t</span>
215 <em class="parameter"><code>contextp</code></em>,
218 <span class="type">lwres_context_t</span>
220 <span class="type">lwres_context_t</span>
221 pointer must initially be NULL, and is modified
222 to point to the newly created
223 <span class="type">lwres_context_t</span>.
227 When the lightweight resolver needs to perform dynamic memory
228 allocation, it will call
229 <em class="parameter"><code>malloc_function</code></em>
230 to allocate memory and
231 <em class="parameter"><code>free_function</code></em>
234 <em class="parameter"><code>malloc_function</code></em>
236 <em class="parameter"><code>free_function</code></em>
238 are NULL, memory is allocated using
241 <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.
243 It is not permitted to have a NULL
244 <em class="parameter"><code>malloc_function</code></em>
246 <em class="parameter"><code>free_function</code></em>
248 <em class="parameter"><code>arg</code></em>
249 is passed as the first parameter to the memory
250 allocation functions.
252 <em class="parameter"><code>malloc_function</code></em>
254 <em class="parameter"><code>free_function</code></em>
256 <em class="parameter"><code>arg</code></em>
258 is unused and should be passed as NULL.
261 Once memory for the structure has been allocated,
262 it is initialized using
263 <span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>
266 <em class="parameter"><code>*contextp</code></em>.
270 <code class="function">lwres_context_destroy()</code>
272 <span class="type">lwres_context_t</span>,
275 <em class="parameter"><code>contextp</code></em>
276 is a pointer to a pointer to the context that is to be destroyed.
277 The pointer will be set to NULL when the context has been destroyed.
280 The context holds a serial number that is used to identify resolver
281 request packets and associate responses with the corresponding requests.
282 This serial number is controlled using
283 <code class="function">lwres_context_initserial()</code>
285 <code class="function">lwres_context_nextserial()</code>.
286 <code class="function">lwres_context_initserial()</code>
287 sets the serial number for context
288 <em class="parameter"><code>*ctx</code></em>
290 <em class="parameter"><code>serial</code></em>.
292 <code class="function">lwres_context_nextserial()</code>
293 increments the serial number and returns the previous value.
296 Memory for a lightweight resolver context is allocated and freed using
297 <code class="function">lwres_context_allocmem()</code>
299 <code class="function">lwres_context_freemem()</code>.
300 These use whatever allocations were defined when the context was
302 <code class="function">lwres_context_create()</code>.
303 <code class="function">lwres_context_allocmem()</code>
305 <em class="parameter"><code>len</code></em>
306 bytes of memory and if successful returns a pointer to the allocated
308 <code class="function">lwres_context_freemem()</code>
310 <em class="parameter"><code>len</code></em>
311 bytes of space starting at location
312 <em class="parameter"><code>mem</code></em>.
316 <code class="function">lwres_context_sendrecv()</code>
317 performs I/O for the context
318 <em class="parameter"><code>ctx</code></em>.
320 Data are read and written from the context's socket.
322 <em class="parameter"><code>sendbase</code></em>
323 — typically a lightweight resolver query packet —
324 and waits for a reply which is copied to the receive buffer at
325 <em class="parameter"><code>recvbase</code></em>.
327 The number of bytes that were written to this receive buffer is
329 <em class="parameter"><code>*recvd_len</code></em>.
333 <div class="refsect1" lang="en">
334 <a name="id2549789"></a><h2>RETURN VALUES</h2>
336 <code class="function">lwres_context_create()</code>
338 <span class="errorcode">LWRES_R_NOMEMORY</span>
340 <span class="type">struct lwres_context</span>
341 could not be allocated,
342 <span class="errorcode">LWRES_R_SUCCESS</span>
346 Successful calls to the memory allocator
347 <code class="function">lwres_context_allocmem()</code>
348 return a pointer to the start of the allocated space.
349 It returns NULL if memory could not be allocated.
352 <span class="errorcode">LWRES_R_SUCCESS</span>
354 <code class="function">lwres_context_sendrecv()</code>
355 completes successfully.
356 <span class="errorcode">LWRES_R_IOERROR</span>
357 is returned if an I/O error occurs and
358 <span class="errorcode">LWRES_R_TIMEOUT</span>
360 <code class="function">lwres_context_sendrecv()</code>
361 times out waiting for a response.
364 <div class="refsect1" lang="en">
365 <a name="id2549841"></a><h2>SEE ALSO</h2>
367 <span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>,
369 <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>,
371 <span class="citerefentry"><span class="refentrytitle">free</span>(3