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 — lightweight resolver context management</p> 29153816Sdougb</div> 30153816Sdougb<div class="refsynopsisdiv"> 31153816Sdougb<h2>Synopsis</h2> 32153816Sdougb<div class="funcsynopsis"> 33153816Sdougb<pre class="funcsynopsisinfo">#include <lwres/lwres.h></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> — typically a 253170222Sdougb lightweight resolver query packet — 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