0797e817daeb2c5ced8982202ed580c42ff57b0f
[dragonfly.git] / contrib / bind-9.5.2 / lib / lwres / man / lwres_context.html
1 <!--
2  - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
3  - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
4  - 
5  - Permission to use, copy, modify, and/or 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.
8  - 
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.
16 -->
17 <!-- $Id: lwres_context.html,v 1.23.214.1 2009/07/11 01:43:31 tbox Exp $ -->
18 <html>
19 <head>
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.71.1">
23 </head>
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="id2476275"></a><div class="titlepage"></div>
26 <div class="refnamediv">
27 <h2>Name</h2>
28 <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>
29 </div>
30 <div class="refsynopsisdiv">
31 <h2>Synopsis</h2>
32 <div class="funcsynopsis">
33 <pre class="funcsynopsisinfo">#include &lt;lwres/lwres.h&gt;</pre>
34 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
35 <tr>
36 <td><code class="funcdef">
37 lwres_result_t
38 <b class="fsfunc">lwres_context_create</b>(</code></td>
39 <td>lwres_context_t ** </td>
40 <td>
41 <var class="pdparam">contextp</var>, </td>
42 </tr>
43 <tr>
44 <td> </td>
45 <td>void * </td>
46 <td>
47 <var class="pdparam">arg</var>, </td>
48 </tr>
49 <tr>
50 <td> </td>
51 <td>lwres_malloc_t  </td>
52 <td>
53 <var class="pdparam">malloc_function</var>, </td>
54 </tr>
55 <tr>
56 <td> </td>
57 <td>lwres_free_t  </td>
58 <td>
59 <var class="pdparam">free_function</var><code>)</code>;</td>
60 </tr>
61 </table>
62 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
63 <td><code class="funcdef">
64 lwres_result_t
65 <b class="fsfunc">lwres_context_destroy</b>(</code></td>
66 <td>lwres_context_t ** </td>
67 <td>
68 <var class="pdparam">contextp</var><code>)</code>;</td>
69 </tr></table>
70 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
71 <tr>
72 <td><code class="funcdef">
73 void
74 <b class="fsfunc">lwres_context_initserial</b>(</code></td>
75 <td>lwres_context_t * </td>
76 <td>
77 <var class="pdparam">ctx</var>, </td>
78 </tr>
79 <tr>
80 <td> </td>
81 <td>lwres_uint32_t  </td>
82 <td>
83 <var class="pdparam">serial</var><code>)</code>;</td>
84 </tr>
85 </table>
86 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
87 <td><code class="funcdef">
88 lwres_uint32_t
89 <b class="fsfunc">lwres_context_nextserial</b>(</code></td>
90 <td>lwres_context_t * </td>
91 <td>
92 <var class="pdparam">ctx</var><code>)</code>;</td>
93 </tr></table>
94 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
95 <tr>
96 <td><code class="funcdef">
97 void
98 <b class="fsfunc">lwres_context_freemem</b>(</code></td>
99 <td>lwres_context_t * </td>
100 <td>
101 <var class="pdparam">ctx</var>, </td>
102 </tr>
103 <tr>
104 <td> </td>
105 <td>void * </td>
106 <td>
107 <var class="pdparam">mem</var>, </td>
108 </tr>
109 <tr>
110 <td> </td>
111 <td>size_t  </td>
112 <td>
113 <var class="pdparam">len</var><code>)</code>;</td>
114 </tr>
115 </table>
116 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
117 <tr>
118 <td><code class="funcdef">
119 void
120 <b class="fsfunc">lwres_context_allocmem</b>(</code></td>
121 <td>lwres_context_t * </td>
122 <td>
123 <var class="pdparam">ctx</var>, </td>
124 </tr>
125 <tr>
126 <td> </td>
127 <td>size_t  </td>
128 <td>
129 <var class="pdparam">len</var><code>)</code>;</td>
130 </tr>
131 </table>
132 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
133 <tr>
134 <td><code class="funcdef">
135 void *
136 <b class="fsfunc">lwres_context_sendrecv</b>(</code></td>
137 <td>lwres_context_t * </td>
138 <td>
139 <var class="pdparam">ctx</var>, </td>
140 </tr>
141 <tr>
142 <td> </td>
143 <td>void * </td>
144 <td>
145 <var class="pdparam">sendbase</var>, </td>
146 </tr>
147 <tr>
148 <td> </td>
149 <td>int  </td>
150 <td>
151 <var class="pdparam">sendlen</var>, </td>
152 </tr>
153 <tr>
154 <td> </td>
155 <td>void * </td>
156 <td>
157 <var class="pdparam">recvbase</var>, </td>
158 </tr>
159 <tr>
160 <td> </td>
161 <td>int  </td>
162 <td>
163 <var class="pdparam">recvlen</var>, </td>
164 </tr>
165 <tr>
166 <td> </td>
167 <td>int * </td>
168 <td>
169 <var class="pdparam">recvd_len</var><code>)</code>;</td>
170 </tr>
171 </table>
172 </div>
173 </div>
174 <div class="refsect1" lang="en">
175 <a name="id2543531"></a><h2>DESCRIPTION</h2>
176 <p><code class="function">lwres_context_create()</code>
177       creates a <span class="type">lwres_context_t</span> structure for use in
178       lightweight resolver operations.  It holds a socket and other
179       data needed for communicating with a resolver daemon.  The new
180       <span class="type">lwres_context_t</span> is returned through
181       <em class="parameter"><code>contextp</code></em>, a pointer to a
182       <span class="type">lwres_context_t</span> pointer.  This
183       <span class="type">lwres_context_t</span> pointer must initially be NULL, and
184       is modified to point to the newly created
185       <span class="type">lwres_context_t</span>.
186     </p>
187 <p>
188       When the lightweight resolver needs to perform dynamic memory
189       allocation, it will call
190       <em class="parameter"><code>malloc_function</code></em>
191       to allocate memory and
192       <em class="parameter"><code>free_function</code></em>
193       to free it.  If
194       <em class="parameter"><code>malloc_function</code></em>
195       and
196       <em class="parameter"><code>free_function</code></em>
197       are NULL, memory is allocated using
198       <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>.
199       and
200       <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.
201
202       It is not permitted to have a NULL
203       <em class="parameter"><code>malloc_function</code></em> and a non-NULL
204       <em class="parameter"><code>free_function</code></em> or vice versa.
205       <em class="parameter"><code>arg</code></em> is passed as the first parameter to
206       the memory allocation functions.  If
207       <em class="parameter"><code>malloc_function</code></em> and
208       <em class="parameter"><code>free_function</code></em> are NULL,
209       <em class="parameter"><code>arg</code></em> is unused and should be passed as
210       NULL.
211     </p>
212 <p>
213       Once memory for the structure has been allocated,
214       it is initialized using
215       <span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>
216       and returned via <em class="parameter"><code>*contextp</code></em>.
217     </p>
218 <p><code class="function">lwres_context_destroy()</code>
219       destroys a <span class="type">lwres_context_t</span>, closing its socket.
220       <em class="parameter"><code>contextp</code></em> is a pointer to a pointer to the
221       context that is to be destroyed.  The pointer will be set to
222       NULL when the context has been destroyed.
223     </p>
224 <p>
225       The context holds a serial number that is used to identify
226       resolver request packets and associate responses with the
227       corresponding requests.  This serial number is controlled using
228       <code class="function">lwres_context_initserial()</code> and
229       <code class="function">lwres_context_nextserial()</code>.
230       <code class="function">lwres_context_initserial()</code> sets the serial
231       number for context <em class="parameter"><code>*ctx</code></em> to
232       <em class="parameter"><code>serial</code></em>.
233       <code class="function">lwres_context_nextserial()</code> increments the
234       serial number and returns the previous value.
235     </p>
236 <p>
237       Memory for a lightweight resolver context is allocated and freed
238       using <code class="function">lwres_context_allocmem()</code> and
239       <code class="function">lwres_context_freemem()</code>.  These use
240       whatever allocations were defined when the context was created
241       with <code class="function">lwres_context_create()</code>.
242       <code class="function">lwres_context_allocmem()</code> allocates
243       <em class="parameter"><code>len</code></em> bytes of memory and if successful
244       returns a pointer to the allocated storage.
245       <code class="function">lwres_context_freemem()</code> frees
246       <em class="parameter"><code>len</code></em> bytes of space starting at location
247       <em class="parameter"><code>mem</code></em>.
248     </p>
249 <p><code class="function">lwres_context_sendrecv()</code>
250       performs I/O for the context <em class="parameter"><code>ctx</code></em>.  Data
251       are read and written from the context's socket.  It writes data
252       from <em class="parameter"><code>sendbase</code></em> &#8212; typically a
253       lightweight resolver query packet &#8212; and waits for a reply
254       which is copied to the receive buffer at
255       <em class="parameter"><code>recvbase</code></em>.  The number of bytes that were
256       written to this receive buffer is returned in
257       <em class="parameter"><code>*recvd_len</code></em>.
258     </p>
259 </div>
260 <div class="refsect1" lang="en">
261 <a name="id2543719"></a><h2>RETURN VALUES</h2>
262 <p><code class="function">lwres_context_create()</code>
263       returns <span class="errorcode">LWRES_R_NOMEMORY</span> if memory for
264       the <span class="type">struct lwres_context</span> could not be allocated,
265       <span class="errorcode">LWRES_R_SUCCESS</span> otherwise.
266     </p>
267 <p>
268       Successful calls to the memory allocator
269       <code class="function">lwres_context_allocmem()</code>
270       return a pointer to the start of the allocated space.
271       It returns NULL if memory could not be allocated.
272     </p>
273 <p><span class="errorcode">LWRES_R_SUCCESS</span>
274       is returned when
275       <code class="function">lwres_context_sendrecv()</code>
276       completes successfully.
277       <span class="errorcode">LWRES_R_IOERROR</span>
278       is returned if an I/O error occurs and
279       <span class="errorcode">LWRES_R_TIMEOUT</span>
280       is returned if
281       <code class="function">lwres_context_sendrecv()</code>
282       times out waiting for a response.
283     </p>
284 </div>
285 <div class="refsect1" lang="en">
286 <a name="id2543769"></a><h2>SEE ALSO</h2>
287 <p><span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>,
288
289       <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>,
290
291       <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.
292     </p>
293 </div>
294 </div></body>
295 </html>