1135446Strhodes<!--
2254897Serwin - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
3153816Sdougb - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
4153816Sdougb - 
5204619Sdougb - Permission to use, copy, modify, and/or distribute this software for any
6135446Strhodes - purpose with or without fee is hereby granted, provided that the above
7135446Strhodes - copyright notice and this permission notice appear in all copies.
8153816Sdougb - 
9135446Strhodes - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10135446Strhodes - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11153816Sdougb - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12135446Strhodes - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13135446Strhodes - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14135446Strhodes - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15135446Strhodes - PERFORMANCE OF THIS SOFTWARE.
16135446Strhodes-->
17234010Sdougb<!-- $Id$ -->
18153816Sdougb<html>
19153816Sdougb<head>
20153816Sdougb<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
21153816Sdougb<title>lwres_context</title>
22170222Sdougb<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
23153816Sdougb</head>
24153816Sdougb<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25225361Sdougb<a name="id2476275"></a><div class="titlepage"></div>
26153816Sdougb<div class="refnamediv">
27153816Sdougb<h2>Name</h2>
28153816Sdougb<p>lwres_context_create, lwres_context_destroy, lwres_context_nextserial, lwres_context_initserial, lwres_context_freemem, lwres_context_allocmem, lwres_context_sendrecv &#8212; lightweight resolver context management</p>
29153816Sdougb</div>
30153816Sdougb<div class="refsynopsisdiv">
31153816Sdougb<h2>Synopsis</h2>
32153816Sdougb<div class="funcsynopsis">
33153816Sdougb<pre class="funcsynopsisinfo">#include &lt;lwres/lwres.h&gt;</pre>
34153816Sdougb<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
35153816Sdougb<tr>
36153816Sdougb<td><code class="funcdef">
37153816Sdougblwres_result_t
38153816Sdougb<b class="fsfunc">lwres_context_create</b>(</code></td>
39170222Sdougb<td>lwres_context_t **�</td>
40170222Sdougb<td>
41170222Sdougb<var class="pdparam">contextp</var>, </td>
42153816Sdougb</tr>
43153816Sdougb<tr>
44153816Sdougb<td>�</td>
45170222Sdougb<td>void *�</td>
46170222Sdougb<td>
47170222Sdougb<var class="pdparam">arg</var>, </td>
48153816Sdougb</tr>
49153816Sdougb<tr>
50153816Sdougb<td>�</td>
51170222Sdougb<td>lwres_malloc_t �</td>
52170222Sdougb<td>
53170222Sdougb<var class="pdparam">malloc_function</var>, </td>
54153816Sdougb</tr>
55153816Sdougb<tr>
56153816Sdougb<td>�</td>
57170222Sdougb<td>lwres_free_t �</td>
58153816Sdougb<td>
59170222Sdougb<var class="pdparam">free_function</var><code>)</code>;</td>
60153816Sdougb</tr>
61153816Sdougb</table>
62170222Sdougb<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
63153816Sdougb<td><code class="funcdef">
64153816Sdougblwres_result_t
65153816Sdougb<b class="fsfunc">lwres_context_destroy</b>(</code></td>
66170222Sdougb<td>lwres_context_t **�</td>
67153816Sdougb<td>
68170222Sdougb<var class="pdparam">contextp</var><code>)</code>;</td>
69170222Sdougb</tr></table>
70153816Sdougb<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
71153816Sdougb<tr>
72153816Sdougb<td><code class="funcdef">
73153816Sdougbvoid
74153816Sdougb<b class="fsfunc">lwres_context_initserial</b>(</code></td>
75170222Sdougb<td>lwres_context_t *�</td>
76170222Sdougb<td>
77170222Sdougb<var class="pdparam">ctx</var>, </td>
78153816Sdougb</tr>
79153816Sdougb<tr>
80153816Sdougb<td>�</td>
81170222Sdougb<td>lwres_uint32_t �</td>
82153816Sdougb<td>
83170222Sdougb<var class="pdparam">serial</var><code>)</code>;</td>
84153816Sdougb</tr>
85153816Sdougb</table>
86170222Sdougb<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
87153816Sdougb<td><code class="funcdef">
88153816Sdougblwres_uint32_t
89153816Sdougb<b class="fsfunc">lwres_context_nextserial</b>(</code></td>
90170222Sdougb<td>lwres_context_t *�</td>
91153816Sdougb<td>
92170222Sdougb<var class="pdparam">ctx</var><code>)</code>;</td>
93170222Sdougb</tr></table>
94153816Sdougb<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
95153816Sdougb<tr>
96153816Sdougb<td><code class="funcdef">
97153816Sdougbvoid
98153816Sdougb<b class="fsfunc">lwres_context_freemem</b>(</code></td>
99170222Sdougb<td>lwres_context_t *�</td>
100170222Sdougb<td>
101170222Sdougb<var class="pdparam">ctx</var>, </td>
102153816Sdougb</tr>
103153816Sdougb<tr>
104153816Sdougb<td>�</td>
105170222Sdougb<td>void *�</td>
106170222Sdougb<td>
107170222Sdougb<var class="pdparam">mem</var>, </td>
108153816Sdougb</tr>
109153816Sdougb<tr>
110153816Sdougb<td>�</td>
111170222Sdougb<td>size_t �</td>
112153816Sdougb<td>
113170222Sdougb<var class="pdparam">len</var><code>)</code>;</td>
114153816Sdougb</tr>
115153816Sdougb</table>
116153816Sdougb<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
117153816Sdougb<tr>
118153816Sdougb<td><code class="funcdef">
119153816Sdougbvoid
120153816Sdougb<b class="fsfunc">lwres_context_allocmem</b>(</code></td>
121170222Sdougb<td>lwres_context_t *�</td>
122170222Sdougb<td>
123170222Sdougb<var class="pdparam">ctx</var>, </td>
124153816Sdougb</tr>
125153816Sdougb<tr>
126153816Sdougb<td>�</td>
127170222Sdougb<td>size_t �</td>
128153816Sdougb<td>
129170222Sdougb<var class="pdparam">len</var><code>)</code>;</td>
130153816Sdougb</tr>
131153816Sdougb</table>
132153816Sdougb<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
133153816Sdougb<tr>
134153816Sdougb<td><code class="funcdef">
135153816Sdougbvoid *
136153816Sdougb<b class="fsfunc">lwres_context_sendrecv</b>(</code></td>
137170222Sdougb<td>lwres_context_t *�</td>
138170222Sdougb<td>
139170222Sdougb<var class="pdparam">ctx</var>, </td>
140153816Sdougb</tr>
141153816Sdougb<tr>
142153816Sdougb<td>�</td>
143170222Sdougb<td>void *�</td>
144170222Sdougb<td>
145170222Sdougb<var class="pdparam">sendbase</var>, </td>
146153816Sdougb</tr>
147153816Sdougb<tr>
148153816Sdougb<td>�</td>
149170222Sdougb<td>int �</td>
150170222Sdougb<td>
151170222Sdougb<var class="pdparam">sendlen</var>, </td>
152153816Sdougb</tr>
153153816Sdougb<tr>
154153816Sdougb<td>�</td>
155170222Sdougb<td>void *�</td>
156170222Sdougb<td>
157170222Sdougb<var class="pdparam">recvbase</var>, </td>
158153816Sdougb</tr>
159153816Sdougb<tr>
160153816Sdougb<td>�</td>
161170222Sdougb<td>int �</td>
162170222Sdougb<td>
163170222Sdougb<var class="pdparam">recvlen</var>, </td>
164153816Sdougb</tr>
165153816Sdougb<tr>
166153816Sdougb<td>�</td>
167170222Sdougb<td>int *�</td>
168153816Sdougb<td>
169170222Sdougb<var class="pdparam">recvd_len</var><code>)</code>;</td>
170153816Sdougb</tr>
171153816Sdougb</table>
172153816Sdougb</div>
173153816Sdougb</div>
174153816Sdougb<div class="refsect1" lang="en">
175254897Serwin<a name="id2543532"></a><h2>DESCRIPTION</h2>
176170222Sdougb<p><code class="function">lwres_context_create()</code>
177170222Sdougb      creates a <span class="type">lwres_context_t</span> structure for use in
178170222Sdougb      lightweight resolver operations.  It holds a socket and other
179170222Sdougb      data needed for communicating with a resolver daemon.  The new
180170222Sdougb      <span class="type">lwres_context_t</span> is returned through
181170222Sdougb      <em class="parameter"><code>contextp</code></em>, a pointer to a
182170222Sdougb      <span class="type">lwres_context_t</span> pointer.  This
183170222Sdougb      <span class="type">lwres_context_t</span> pointer must initially be NULL, and
184170222Sdougb      is modified to point to the newly created
185170222Sdougb      <span class="type">lwres_context_t</span>.
186170222Sdougb    </p>
187153816Sdougb<p>
188170222Sdougb      When the lightweight resolver needs to perform dynamic memory
189170222Sdougb      allocation, it will call
190170222Sdougb      <em class="parameter"><code>malloc_function</code></em>
191170222Sdougb      to allocate memory and
192170222Sdougb      <em class="parameter"><code>free_function</code></em>
193170222Sdougb      to free it.  If
194170222Sdougb      <em class="parameter"><code>malloc_function</code></em>
195170222Sdougb      and
196170222Sdougb      <em class="parameter"><code>free_function</code></em>
197170222Sdougb      are NULL, memory is allocated using
198170222Sdougb      <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>.
199170222Sdougb      and
200170222Sdougb      <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.
201135446Strhodes
202170222Sdougb      It is not permitted to have a NULL
203170222Sdougb      <em class="parameter"><code>malloc_function</code></em> and a non-NULL
204170222Sdougb      <em class="parameter"><code>free_function</code></em> or vice versa.
205170222Sdougb      <em class="parameter"><code>arg</code></em> is passed as the first parameter to
206170222Sdougb      the memory allocation functions.  If
207170222Sdougb      <em class="parameter"><code>malloc_function</code></em> and
208170222Sdougb      <em class="parameter"><code>free_function</code></em> are NULL,
209170222Sdougb      <em class="parameter"><code>arg</code></em> is unused and should be passed as
210170222Sdougb      NULL.
211170222Sdougb    </p>
212153816Sdougb<p>
213170222Sdougb      Once memory for the structure has been allocated,
214170222Sdougb      it is initialized using
215170222Sdougb      <span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>
216170222Sdougb      and returned via <em class="parameter"><code>*contextp</code></em>.
217170222Sdougb    </p>
218170222Sdougb<p><code class="function">lwres_context_destroy()</code>
219170222Sdougb      destroys a <span class="type">lwres_context_t</span>, closing its socket.
220170222Sdougb      <em class="parameter"><code>contextp</code></em> is a pointer to a pointer to the
221170222Sdougb      context that is to be destroyed.  The pointer will be set to
222170222Sdougb      NULL when the context has been destroyed.
223170222Sdougb    </p>
224153816Sdougb<p>
225170222Sdougb      The context holds a serial number that is used to identify
226170222Sdougb      resolver request packets and associate responses with the
227170222Sdougb      corresponding requests.  This serial number is controlled using
228170222Sdougb      <code class="function">lwres_context_initserial()</code> and
229170222Sdougb      <code class="function">lwres_context_nextserial()</code>.
230170222Sdougb      <code class="function">lwres_context_initserial()</code> sets the serial
231170222Sdougb      number for context <em class="parameter"><code>*ctx</code></em> to
232170222Sdougb      <em class="parameter"><code>serial</code></em>.
233170222Sdougb      <code class="function">lwres_context_nextserial()</code> increments the
234170222Sdougb      serial number and returns the previous value.
235170222Sdougb    </p>
236153816Sdougb<p>
237170222Sdougb      Memory for a lightweight resolver context is allocated and freed
238170222Sdougb      using <code class="function">lwres_context_allocmem()</code> and
239170222Sdougb      <code class="function">lwres_context_freemem()</code>.  These use
240170222Sdougb      whatever allocations were defined when the context was created
241170222Sdougb      with <code class="function">lwres_context_create()</code>.
242170222Sdougb      <code class="function">lwres_context_allocmem()</code> allocates
243170222Sdougb      <em class="parameter"><code>len</code></em> bytes of memory and if successful
244170222Sdougb      returns a pointer to the allocated storage.
245170222Sdougb      <code class="function">lwres_context_freemem()</code> frees
246170222Sdougb      <em class="parameter"><code>len</code></em> bytes of space starting at location
247170222Sdougb      <em class="parameter"><code>mem</code></em>.
248170222Sdougb    </p>
249170222Sdougb<p><code class="function">lwres_context_sendrecv()</code>
250170222Sdougb      performs I/O for the context <em class="parameter"><code>ctx</code></em>.  Data
251170222Sdougb      are read and written from the context's socket.  It writes data
252170222Sdougb      from <em class="parameter"><code>sendbase</code></em> &#8212; typically a
253170222Sdougb      lightweight resolver query packet &#8212; and waits for a reply
254170222Sdougb      which is copied to the receive buffer at
255170222Sdougb      <em class="parameter"><code>recvbase</code></em>.  The number of bytes that were
256170222Sdougb      written to this receive buffer is returned in
257170222Sdougb      <em class="parameter"><code>*recvd_len</code></em>.
258170222Sdougb    </p>
259153816Sdougb</div>
260153816Sdougb<div class="refsect1" lang="en">
261254897Serwin<a name="id2543720"></a><h2>RETURN VALUES</h2>
262170222Sdougb<p><code class="function">lwres_context_create()</code>
263170222Sdougb      returns <span class="errorcode">LWRES_R_NOMEMORY</span> if memory for
264170222Sdougb      the <span class="type">struct lwres_context</span> could not be allocated,
265170222Sdougb      <span class="errorcode">LWRES_R_SUCCESS</span> otherwise.
266170222Sdougb    </p>
267153816Sdougb<p>
268170222Sdougb      Successful calls to the memory allocator
269170222Sdougb      <code class="function">lwres_context_allocmem()</code>
270170222Sdougb      return a pointer to the start of the allocated space.
271170222Sdougb      It returns NULL if memory could not be allocated.
272170222Sdougb    </p>
273170222Sdougb<p><span class="errorcode">LWRES_R_SUCCESS</span>
274170222Sdougb      is returned when
275170222Sdougb      <code class="function">lwres_context_sendrecv()</code>
276170222Sdougb      completes successfully.
277170222Sdougb      <span class="errorcode">LWRES_R_IOERROR</span>
278170222Sdougb      is returned if an I/O error occurs and
279170222Sdougb      <span class="errorcode">LWRES_R_TIMEOUT</span>
280170222Sdougb      is returned if
281170222Sdougb      <code class="function">lwres_context_sendrecv()</code>
282170222Sdougb      times out waiting for a response.
283170222Sdougb    </p>
284153816Sdougb</div>
285153816Sdougb<div class="refsect1" lang="en">
286254897Serwin<a name="id2543770"></a><h2>SEE ALSO</h2>
287170222Sdougb<p><span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>,
288135446Strhodes
289170222Sdougb      <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>,
290135446Strhodes
291170222Sdougb      <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.
292170222Sdougb    </p>
293153816Sdougb</div>
294153816Sdougb</div></body>
295153816Sdougb</html>
296