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