external/bsd/bind/dist/lib/lwres/man/lwres_noop.html

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2000, 2001 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 -->
  18 <html>
  19 <head>
  20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  21 <title>lwres_noop</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_nooprequest_render, lwres_noopresponse_render, lwres_nooprequest_parse, lwres_noopresponse_parse, lwres_noopresponse_free, lwres_nooprequest_free &#8212; lightweight resolver no-op message handling</p>
  29 </div>
  30 <div class="refsynopsisdiv">
  31 <h2>Synopsis</h2>
  32 <div class="funcsynopsis">
  33 <pre class="funcsynopsisinfo">
  34 #include &lt;lwres/lwres.h&gt;</pre>
  35 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  36 <tr>
  37 <td><code class="funcdef">
  38 lwres_result_t
  39 <b class="fsfunc">lwres_nooprequest_render</b>(</code></td>
  40 <td>lwres_context_t * </td>
  41 <td>
  42 <var class="pdparam">ctx</var>, </td>
  43 </tr>
  44 <tr>
  45 <td> </td>
  46 <td>lwres_nooprequest_t * </td>
  47 <td>
  48 <var class="pdparam">req</var>, </td>
  49 </tr>
  50 <tr>
  51 <td> </td>
  52 <td>lwres_lwpacket_t * </td>
  53 <td>
  54 <var class="pdparam">pkt</var>, </td>
  55 </tr>
  56 <tr>
  57 <td> </td>
  58 <td>lwres_buffer_t * </td>
  59 <td>
  60 <var class="pdparam">b</var><code>)</code>;</td>
  61 </tr>
  62 </table>
  63 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  64 <tr>
  65 <td><code class="funcdef">
  66 lwres_result_t
  67 <b class="fsfunc">lwres_noopresponse_render</b>(</code></td>
  68 <td>lwres_context_t * </td>
  69 <td>
  70 <var class="pdparam">ctx</var>, </td>
  71 </tr>
  72 <tr>
  73 <td> </td>
  74 <td>lwres_noopresponse_t * </td>
  75 <td>
  76 <var class="pdparam">req</var>, </td>
  77 </tr>
  78 <tr>
  79 <td> </td>
  80 <td>lwres_lwpacket_t * </td>
  81 <td>
  82 <var class="pdparam">pkt</var>, </td>
  83 </tr>
  84 <tr>
  85 <td> </td>
  86 <td>lwres_buffer_t * </td>
  87 <td>
  88 <var class="pdparam">b</var><code>)</code>;</td>
  89 </tr>
  90 </table>
  91 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  92 <tr>
  93 <td><code class="funcdef">
  94 lwres_result_t
  95 <b class="fsfunc">lwres_nooprequest_parse</b>(</code></td>
  96 <td>lwres_context_t * </td>
  97 <td>
  98 <var class="pdparam">ctx</var>, </td>
  99 </tr>
 100 <tr>
 101 <td> </td>
 102 <td>lwres_buffer_t * </td>
 103 <td>
 104 <var class="pdparam">b</var>, </td>
 105 </tr>
 106 <tr>
 107 <td> </td>
 108 <td>lwres_lwpacket_t * </td>
 109 <td>
 110 <var class="pdparam">pkt</var>, </td>
 111 </tr>
 112 <tr>
 113 <td> </td>
 114 <td>lwres_nooprequest_t ** </td>
 115 <td>
 116 <var class="pdparam">structp</var><code>)</code>;</td>
 117 </tr>
 118 </table>
 119 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 120 <tr>
 121 <td><code class="funcdef">
 122 lwres_result_t
 123 <b class="fsfunc">lwres_noopresponse_parse</b>(</code></td>
 124 <td>lwres_context_t * </td>
 125 <td>
 126 <var class="pdparam">ctx</var>, </td>
 127 </tr>
 128 <tr>
 129 <td> </td>
 130 <td>lwres_buffer_t * </td>
 131 <td>
 132 <var class="pdparam">b</var>, </td>
 133 </tr>
 134 <tr>
 135 <td> </td>
 136 <td>lwres_lwpacket_t * </td>
 137 <td>
 138 <var class="pdparam">pkt</var>, </td>
 139 </tr>
 140 <tr>
 141 <td> </td>
 142 <td>lwres_noopresponse_t ** </td>
 143 <td>
 144 <var class="pdparam">structp</var><code>)</code>;</td>
 145 </tr>
 146 </table>
 147 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 148 <tr>
 149 <td><code class="funcdef">
 150 void
 151 <b class="fsfunc">lwres_noopresponse_free</b>(</code></td>
 152 <td>lwres_context_t * </td>
 153 <td>
 154 <var class="pdparam">ctx</var>, </td>
 155 </tr>
 156 <tr>
 157 <td> </td>
 158 <td>lwres_noopresponse_t ** </td>
 159 <td>
 160 <var class="pdparam">structp</var><code>)</code>;</td>
 161 </tr>
 162 </table>
 163 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
 164 <tr>
 165 <td><code class="funcdef">
 166 void
 167 <b class="fsfunc">lwres_nooprequest_free</b>(</code></td>
 168 <td>lwres_context_t * </td>
 169 <td>
 170 <var class="pdparam">ctx</var>, </td>
 171 </tr>
 172 <tr>
 173 <td> </td>
 174 <td>lwres_nooprequest_t ** </td>
 175 <td>
 176 <var class="pdparam">structp</var><code>)</code>;</td>
 177 </tr>
 178 </table>
 179 </div>
 180 </div>
 181 <div class="refsect1" lang="en">
 182 <a name="id2543531"></a><h2>DESCRIPTION</h2>
 183 <p>
 184       These are low-level routines for creating and parsing
 185       lightweight resolver no-op request and response messages.
 186     </p>
 187 <p>
 188       The no-op message is analogous to a <span><strong class="command">ping</strong></span>
 189       packet:
 190       a packet is sent to the resolver daemon and is simply echoed back.
 191       The opcode is intended to allow a client to determine if the server is
 192       operational or not.
 193     </p>
 194 <p>
 195       There are four main functions for the no-op opcode.
 196       One render function converts a no-op request structure &#8212;
 197       <span class="type">lwres_nooprequest_t</span> &#8212;
 198       to the lightweight resolver's canonical format.
 199       It is complemented by a parse function that converts a packet in this
 200       canonical format to a no-op request structure.
 201       Another render function converts the no-op response structure &#8212;
 202       <span class="type">lwres_noopresponse_t</span>
 203       to the canonical format.
 204       This is complemented by a parse function which converts a packet in
 205       canonical format to a no-op response structure.
 206     </p>
 207 <p>
 208       These structures are defined in
 209       <code class="filename">lwres/lwres.h</code>.
 210
 211       They are shown below.
 212     </p>
 213 <pre class="programlisting">
 214 #define LWRES_OPCODE_NOOP       0x00000000U
 215 </pre>
 216 <p>
 217     </p>
 218 <pre class="programlisting">
 219 typedef struct {
 220         lwres_uint16_t  datalength;
 221         unsigned char   *data;
 222 } lwres_nooprequest_t;
 223 </pre>
 224 <p>
 225     </p>
 226 <pre class="programlisting">
 227 typedef struct {
 228         lwres_uint16_t  datalength;
 229         unsigned char   *data;
 230 } lwres_noopresponse_t;
 231 </pre>
 232 <p>
 233     </p>
 234 <p>
 235       Although the structures have different types, they are identical.
 236       This is because the no-op opcode simply echos whatever data was sent:
 237       the response is therefore identical to the request.
 238     </p>
 239 <p><code class="function">lwres_nooprequest_render()</code>
 240       uses resolver context <em class="parameter"><code>ctx</code></em> to convert
 241       no-op request structure <em class="parameter"><code>req</code></em> to canonical
 242       format.  The packet header structure <em class="parameter"><code>pkt</code></em>
 243       is initialised and transferred to buffer
 244       <em class="parameter"><code>b</code></em>.  The contents of
 245       <em class="parameter"><code>*req</code></em> are then appended to the buffer in
 246       canonical format.
 247       <code class="function">lwres_noopresponse_render()</code> performs the
 248       same task, except it converts a no-op response structure
 249       <span class="type">lwres_noopresponse_t</span> to the lightweight resolver's
 250       canonical format.
 251     </p>
 252 <p><code class="function">lwres_nooprequest_parse()</code>
 253       uses context <em class="parameter"><code>ctx</code></em> to convert the contents
 254       of packet <em class="parameter"><code>pkt</code></em> to a
 255       <span class="type">lwres_nooprequest_t</span> structure.  Buffer
 256       <em class="parameter"><code>b</code></em> provides space to be used for storing
 257       this structure.  When the function succeeds, the resulting
 258       <span class="type">lwres_nooprequest_t</span> is made available through
 259       <em class="parameter"><code>*structp</code></em>.
 260       <code class="function">lwres_noopresponse_parse()</code> offers the same
 261       semantics as <code class="function">lwres_nooprequest_parse()</code>
 262       except it yields a <span class="type">lwres_noopresponse_t</span> structure.
 263     </p>
 264 <p><code class="function">lwres_noopresponse_free()</code>
 265       and <code class="function">lwres_nooprequest_free()</code> release the
 266       memory in resolver context <em class="parameter"><code>ctx</code></em> that was
 267       allocated to the <span class="type">lwres_noopresponse_t</span> or
 268       <span class="type">lwres_nooprequest_t</span> structures referenced via
 269       <em class="parameter"><code>structp</code></em>.
 270     </p>
 271 </div>
 272 <div class="refsect1" lang="en">
 273 <a name="id2543682"></a><h2>RETURN VALUES</h2>
 274 <p>
 275       The no-op opcode functions
 276       <code class="function">lwres_nooprequest_render()</code>,
 277
 278       <code class="function">lwres_noopresponse_render()</code>
 279       <code class="function">lwres_nooprequest_parse()</code>
 280       and
 281       <code class="function">lwres_noopresponse_parse()</code>
 282       all return
 283       <span class="errorcode">LWRES_R_SUCCESS</span>
 284       on success.
 285       They return
 286       <span class="errorcode">LWRES_R_NOMEMORY</span>
 287       if memory allocation fails.
 288       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 289       is returned if the available space in the buffer
 290       <em class="parameter"><code>b</code></em>
 291       is too small to accommodate the packet header or the
 292       <span class="type">lwres_nooprequest_t</span>
 293       and
 294       <span class="type">lwres_noopresponse_t</span>
 295       structures.
 296       <code class="function">lwres_nooprequest_parse()</code>
 297       and
 298       <code class="function">lwres_noopresponse_parse()</code>
 299       will return
 300       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 301       if the buffer is not empty after decoding the received packet.
 302       These functions will return
 303       <span class="errorcode">LWRES_R_FAILURE</span>
 304       if
 305       <code class="constant">pktflags</code>
 306       in the packet header structure
 307       <span class="type">lwres_lwpacket_t</span>
 308       indicate that the packet is not a response to an earlier query.
 309     </p>
 310 </div>
 311 <div class="refsect1" lang="en">
 312 <a name="id2543748"></a><h2>SEE ALSO</h2>
 313 <p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>
 314     </p>
 315 </div>
 316 </div></body>
 317 </html>