1<!-- 2 - Copyright (C) 2004, 2005, 2007, 2014 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 --> 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 — lightweight resolver context management</p> 29</div> 30<div class="refsynopsisdiv"> 31<h2>Synopsis</h2> 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"> 35<tr> 36<td><code class="funcdef"> 37lwres_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"> 64lwres_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"> 73void 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"> 88lwres_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"> 97void 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"> 119void 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"> 135void * 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="id2543541"></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> — typically a 253 lightweight resolver query packet — 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="id2543729"></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="id2543779"></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> 296