contrib/bind-9.3/lib/lwres/man/lwres_context.html

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