contrib/bind9/lib/lwres/man/lwres_context.html

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007, 2014, 2015 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 <html>
  18 <head>
  19 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  20 <title>lwres_context</title>
  21 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
  22 </head>
  23 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
  24 <a name="id-1"></a><div class="titlepage"></div>
  25 <div class="refnamediv">
  26 <h2>Name</h2>
  27 <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>
  28 </div>
  29 <div class="refsynopsisdiv">
  30 <h2>Synopsis</h2>
  31 <div class="funcsynopsis">
  32 <pre class="funcsynopsisinfo">#include &lt;lwres/lwres.h&gt;</pre>
  33 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  34 <tr>
  35 <td><code class="funcdef">
  36 lwres_result_t
  37 <b class="fsfunc">lwres_context_create</b>(</code></td>
  38 <td>lwres_context_t **<var class="pdparam">contextp</var>, </td>
  39 </tr>
  40 <tr>
  41 <td> </td>
  42 <td>void *<var class="pdparam">arg</var>, </td>
  43 </tr>
  44 <tr>
  45 <td> </td>
  46 <td>lwres_malloc_t <var class="pdparam">malloc_function</var>, </td>
  47 </tr>
  48 <tr>
  49 <td> </td>
  50 <td>lwres_free_t <var class="pdparam">free_function</var><code>)</code>;</td>
  51 </tr>
  52 </table>
  53 <div class="funcprototype-spacer"> </div>
  54 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
  55 <td><code class="funcdef">
  56 lwres_result_t
  57 <b class="fsfunc">lwres_context_destroy</b>(</code></td>
  58 <td>lwres_context_t **<var class="pdparam">contextp</var><code>)</code>;</td>
  59 </tr></table>
  60 <div class="funcprototype-spacer"> </div>
  61 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  62 <tr>
  63 <td><code class="funcdef">
  64 void
  65 <b class="fsfunc">lwres_context_initserial</b>(</code></td>
  66 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
  67 </tr>
  68 <tr>
  69 <td> </td>
  70 <td>lwres_uint32_t <var class="pdparam">serial</var><code>)</code>;</td>
  71 </tr>
  72 </table>
  73 <div class="funcprototype-spacer"> </div>
  74 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
  75 <td><code class="funcdef">
  76 lwres_uint32_t
  77 <b class="fsfunc">lwres_context_nextserial</b>(</code></td>
  78 <td>lwres_context_t *<var class="pdparam">ctx</var><code>)</code>;</td>
  79 </tr></table>
  80 <div class="funcprototype-spacer"> </div>
  81 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  82 <tr>
  83 <td><code class="funcdef">
  84 void
  85 <b class="fsfunc">lwres_context_freemem</b>(</code></td>
  86 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
  87 </tr>
  88 <tr>
  89 <td> </td>
  90 <td>void *<var class="pdparam">mem</var>, </td>
  91 </tr>
  92 <tr>
  93 <td> </td>
  94 <td>size_t <var class="pdparam">len</var><code>)</code>;</td>
  95 </tr>
  96 </table>
  97 <div class="funcprototype-spacer"> </div>
  98 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  99 <tr>
 100 <td><code class="funcdef">
 101 void
 102 <b class="fsfunc">lwres_context_allocmem</b>(</code></td>
 103 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
 104 </tr>
 105 <tr>
 106 <td> </td>
 107 <td>size_t <var class="pdparam">len</var><code>)</code>;</td>
 108 </tr>
 109 </table>
 110 <div class="funcprototype-spacer"> </div>
 111 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 112 <tr>
 113 <td><code class="funcdef">
 114 void *
 115 <b class="fsfunc">lwres_context_sendrecv</b>(</code></td>
 116 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
 117 </tr>
 118 <tr>
 119 <td> </td>
 120 <td>void *<var class="pdparam">sendbase</var>, </td>
 121 </tr>
 122 <tr>
 123 <td> </td>
 124 <td>int <var class="pdparam">sendlen</var>, </td>
 125 </tr>
 126 <tr>
 127 <td> </td>
 128 <td>void *<var class="pdparam">recvbase</var>, </td>
 129 </tr>
 130 <tr>
 131 <td> </td>
 132 <td>int <var class="pdparam">recvlen</var>, </td>
 133 </tr>
 134 <tr>
 135 <td> </td>
 136 <td>int *<var class="pdparam">recvd_len</var><code>)</code>;</td>
 137 </tr>
 138 </table>
 139 <div class="funcprototype-spacer"> </div>
 140 </div>
 141 </div>
 142 <div class="refsection">
 143 <a name="id-1.7"></a><h2>DESCRIPTION</h2>
 144 <p><code class="function">lwres_context_create()</code>
 145       creates a <span class="type">lwres_context_t</span> structure for use in
 146       lightweight resolver operations.  It holds a socket and other
 147       data needed for communicating with a resolver daemon.  The new
 148       <span class="type">lwres_context_t</span> is returned through
 149       <em class="parameter"><code>contextp</code></em>, a pointer to a
 150       <span class="type">lwres_context_t</span> pointer.  This
 151       <span class="type">lwres_context_t</span> pointer must initially be NULL, and
 152       is modified to point to the newly created
 153       <span class="type">lwres_context_t</span>.
 154     </p>
 155 <p>
 156       When the lightweight resolver needs to perform dynamic memory
 157       allocation, it will call
 158       <em class="parameter"><code>malloc_function</code></em>
 159       to allocate memory and
 160       <em class="parameter"><code>free_function</code></em>
 161       to free it.  If
 162       <em class="parameter"><code>malloc_function</code></em>
 163       and
 164       <em class="parameter"><code>free_function</code></em>
 165       are NULL, memory is allocated using
 166       <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>.
 167       and
 168       <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.
 169
 170       It is not permitted to have a NULL
 171       <em class="parameter"><code>malloc_function</code></em> and a non-NULL
 172       <em class="parameter"><code>free_function</code></em> or vice versa.
 173       <em class="parameter"><code>arg</code></em> is passed as the first parameter to
 174       the memory allocation functions.  If
 175       <em class="parameter"><code>malloc_function</code></em> and
 176       <em class="parameter"><code>free_function</code></em> are NULL,
 177       <em class="parameter"><code>arg</code></em> is unused and should be passed as
 178       NULL.
 179     </p>
 180 <p>
 181       Once memory for the structure has been allocated,
 182       it is initialized using
 183       <span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>
 184       and returned via <em class="parameter"><code>*contextp</code></em>.
 185     </p>
 186 <p><code class="function">lwres_context_destroy()</code>
 187       destroys a <span class="type">lwres_context_t</span>, closing its socket.
 188       <em class="parameter"><code>contextp</code></em> is a pointer to a pointer to the
 189       context that is to be destroyed.  The pointer will be set to
 190       NULL when the context has been destroyed.
 191     </p>
 192 <p>
 193       The context holds a serial number that is used to identify
 194       resolver request packets and associate responses with the
 195       corresponding requests.  This serial number is controlled using
 196       <code class="function">lwres_context_initserial()</code> and
 197       <code class="function">lwres_context_nextserial()</code>.
 198       <code class="function">lwres_context_initserial()</code> sets the serial
 199       number for context <em class="parameter"><code>*ctx</code></em> to
 200       <em class="parameter"><code>serial</code></em>.
 201       <code class="function">lwres_context_nextserial()</code> increments the
 202       serial number and returns the previous value.
 203     </p>
 204 <p>
 205       Memory for a lightweight resolver context is allocated and freed
 206       using <code class="function">lwres_context_allocmem()</code> and
 207       <code class="function">lwres_context_freemem()</code>.  These use
 208       whatever allocations were defined when the context was created
 209       with <code class="function">lwres_context_create()</code>.
 210       <code class="function">lwres_context_allocmem()</code> allocates
 211       <em class="parameter"><code>len</code></em> bytes of memory and if successful
 212       returns a pointer to the allocated storage.
 213       <code class="function">lwres_context_freemem()</code> frees
 214       <em class="parameter"><code>len</code></em> bytes of space starting at location
 215       <em class="parameter"><code>mem</code></em>.
 216     </p>
 217 <p><code class="function">lwres_context_sendrecv()</code>
 218       performs I/O for the context <em class="parameter"><code>ctx</code></em>.  Data
 219       are read and written from the context's socket.  It writes data
 220       from <em class="parameter"><code>sendbase</code></em> &#8212; typically a
 221       lightweight resolver query packet &#8212; and waits for a reply
 222       which is copied to the receive buffer at
 223       <em class="parameter"><code>recvbase</code></em>.  The number of bytes that were
 224       written to this receive buffer is returned in
 225       <em class="parameter"><code>*recvd_len</code></em>.
 226     </p>
 227 </div>
 228 <div class="refsection">
 229 <a name="id-1.8"></a><h2>RETURN VALUES</h2>
 230 <p><code class="function">lwres_context_create()</code>
 231       returns <span class="errorcode">LWRES_R_NOMEMORY</span> if memory for
 232       the <span class="type">struct lwres_context</span> could not be allocated,
 233       <span class="errorcode">LWRES_R_SUCCESS</span> otherwise.
 234     </p>
 235 <p>
 236       Successful calls to the memory allocator
 237       <code class="function">lwres_context_allocmem()</code>
 238       return a pointer to the start of the allocated space.
 239       It returns NULL if memory could not be allocated.
 240     </p>
 241 <p><span class="errorcode">LWRES_R_SUCCESS</span>
 242       is returned when
 243       <code class="function">lwres_context_sendrecv()</code>
 244       completes successfully.
 245       <span class="errorcode">LWRES_R_IOERROR</span>
 246       is returned if an I/O error occurs and
 247       <span class="errorcode">LWRES_R_TIMEOUT</span>
 248       is returned if
 249       <code class="function">lwres_context_sendrecv()</code>
 250       times out waiting for a response.
 251     </p>
 252 </div>
 253 <div class="refsection">
 254 <a name="id-1.9"></a><h2>SEE ALSO</h2>
 255 <p><span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>,
 256
 257       <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>,
 258
 259       <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.
 260     </p>
 261 </div>
 262 </div></body>
 263 </html>