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>