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

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007, 2014, 2015 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 <html>
  18 <head>
  19 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  20 <title>lwres_gabn</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_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free &#8212; lightweight resolver getaddrbyname message handling</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_gabnrequest_render</b>(</code></td>
  38 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
  39 </tr>
  40 <tr>
  41 <td> </td>
  42 <td>lwres_gabnrequest_t *<var class="pdparam">req</var>, </td>
  43 </tr>
  44 <tr>
  45 <td> </td>
  46 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
  47 </tr>
  48 <tr>
  49 <td> </td>
  50 <td>lwres_buffer_t *<var class="pdparam">b</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;">
  55 <tr>
  56 <td><code class="funcdef">
  57 lwres_result_t
  58 <b class="fsfunc">lwres_gabnresponse_render</b>(</code></td>
  59 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
  60 </tr>
  61 <tr>
  62 <td> </td>
  63 <td>lwres_gabnresponse_t *<var class="pdparam">req</var>, </td>
  64 </tr>
  65 <tr>
  66 <td> </td>
  67 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
  68 </tr>
  69 <tr>
  70 <td> </td>
  71 <td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
  72 </tr>
  73 </table>
  74 <div class="funcprototype-spacer"> </div>
  75 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  76 <tr>
  77 <td><code class="funcdef">
  78 lwres_result_t
  79 <b class="fsfunc">lwres_gabnrequest_parse</b>(</code></td>
  80 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
  81 </tr>
  82 <tr>
  83 <td> </td>
  84 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
  85 </tr>
  86 <tr>
  87 <td> </td>
  88 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
  89 </tr>
  90 <tr>
  91 <td> </td>
  92 <td>lwres_gabnrequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
  93 </tr>
  94 </table>
  95 <div class="funcprototype-spacer"> </div>
  96 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  97 <tr>
  98 <td><code class="funcdef">
  99 lwres_result_t
 100 <b class="fsfunc">lwres_gabnresponse_parse</b>(</code></td>
 101 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
 102 </tr>
 103 <tr>
 104 <td> </td>
 105 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
 106 </tr>
 107 <tr>
 108 <td> </td>
 109 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
 110 </tr>
 111 <tr>
 112 <td> </td>
 113 <td>lwres_gabnresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
 114 </tr>
 115 </table>
 116 <div class="funcprototype-spacer"> </div>
 117 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 118 <tr>
 119 <td><code class="funcdef">
 120 void
 121 <b class="fsfunc">lwres_gabnresponse_free</b>(</code></td>
 122 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
 123 </tr>
 124 <tr>
 125 <td> </td>
 126 <td>lwres_gabnresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
 127 </tr>
 128 </table>
 129 <div class="funcprototype-spacer"> </div>
 130 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 131 <tr>
 132 <td><code class="funcdef">
 133 void
 134 <b class="fsfunc">lwres_gabnrequest_free</b>(</code></td>
 135 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
 136 </tr>
 137 <tr>
 138 <td> </td>
 139 <td>lwres_gabnrequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
 140 </tr>
 141 </table>
 142 <div class="funcprototype-spacer"> </div>
 143 </div>
 144 </div>
 145 <div class="refsection">
 146 <a name="id-1.7"></a><h2>DESCRIPTION</h2>
 147 <p>
 148       These are low-level routines for creating and parsing
 149       lightweight resolver name-to-address lookup request and
 150       response messages.
 151     </p>
 152 <p>
 153       There are four main functions for the getaddrbyname opcode.
 154       One render function converts a getaddrbyname request structure &#8212;
 155       <span class="type">lwres_gabnrequest_t</span> &#8212;
 156       to the lightweight resolver's canonical format.
 157       It is complemented by a parse function that converts a packet in this
 158       canonical format to a getaddrbyname request structure.
 159       Another render function converts the getaddrbyname response structure
 160       &#8212; <span class="type">lwres_gabnresponse_t</span> &#8212;
 161       to the canonical format.
 162       This is complemented by a parse function which converts a packet in
 163       canonical format to a getaddrbyname response structure.
 164     </p>
 165 <p>
 166       These structures are defined in
 167       <code class="filename">&lt;lwres/lwres.h&gt;</code>.
 168       They are shown below.
 169     </p>
 170 <pre class="programlisting">
 171 #define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
 172 </pre>
 173 <p>
 174     </p>
 175 <pre class="programlisting">
 176 typedef struct lwres_addr lwres_addr_t;
 177 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
 178 </pre>
 179 <p>
 180     </p>
 181 <pre class="programlisting">
 182 typedef struct {
 183         lwres_uint32_t  flags;
 184         lwres_uint32_t  addrtypes;
 185         lwres_uint16_t  namelen;
 186         char           *name;
 187 } lwres_gabnrequest_t;
 188 </pre>
 189 <p>
 190     </p>
 191 <pre class="programlisting">
 192 typedef struct {
 193         lwres_uint32_t          flags;
 194         lwres_uint16_t          naliases;
 195         lwres_uint16_t          naddrs;
 196         char                   *realname;
 197         char                  **aliases;
 198         lwres_uint16_t          realnamelen;
 199         lwres_uint16_t         *aliaslen;
 200         lwres_addrlist_t        addrs;
 201         void                   *base;
 202         size_t                  baselen;
 203 } lwres_gabnresponse_t;
 204 </pre>
 205 <p>
 206     </p>
 207 <p><code class="function">lwres_gabnrequest_render()</code>
 208       uses resolver context <em class="parameter"><code>ctx</code></em> to convert
 209       getaddrbyname request structure <em class="parameter"><code>req</code></em> to
 210       canonical format.  The packet header structure
 211       <em class="parameter"><code>pkt</code></em> is initialised and transferred to
 212       buffer <em class="parameter"><code>b</code></em>.
 213
 214       The contents of <em class="parameter"><code>*req</code></em> are then appended to
 215       the buffer in canonical format.
 216       <code class="function">lwres_gabnresponse_render()</code> performs the
 217       same task, except it converts a getaddrbyname response structure
 218       <span class="type">lwres_gabnresponse_t</span> to the lightweight resolver's
 219       canonical format.
 220     </p>
 221 <p><code class="function">lwres_gabnrequest_parse()</code>
 222       uses context <em class="parameter"><code>ctx</code></em> to convert the contents
 223       of packet <em class="parameter"><code>pkt</code></em> to a
 224       <span class="type">lwres_gabnrequest_t</span> structure.  Buffer
 225       <em class="parameter"><code>b</code></em> provides space to be used for storing
 226       this structure.  When the function succeeds, the resulting
 227       <span class="type">lwres_gabnrequest_t</span> is made available through
 228       <em class="parameter"><code>*structp</code></em>.
 229
 230       <code class="function">lwres_gabnresponse_parse()</code> offers the same
 231       semantics as <code class="function">lwres_gabnrequest_parse()</code>
 232       except it yields a <span class="type">lwres_gabnresponse_t</span> structure.
 233     </p>
 234 <p><code class="function">lwres_gabnresponse_free()</code>
 235       and <code class="function">lwres_gabnrequest_free()</code> release the
 236       memory in resolver context <em class="parameter"><code>ctx</code></em> that was
 237       allocated to the <span class="type">lwres_gabnresponse_t</span> or
 238       <span class="type">lwres_gabnrequest_t</span> structures referenced via
 239       <em class="parameter"><code>structp</code></em>.
 240
 241       Any memory associated with ancillary buffers and strings for
 242       those structures is also discarded.
 243     </p>
 244 </div>
 245 <div class="refsection">
 246 <a name="id-1.8"></a><h2>RETURN VALUES</h2>
 247 <p>
 248       The getaddrbyname opcode functions
 249       <code class="function">lwres_gabnrequest_render()</code>,
 250       <code class="function">lwres_gabnresponse_render()</code>
 251       <code class="function">lwres_gabnrequest_parse()</code>
 252       and
 253       <code class="function">lwres_gabnresponse_parse()</code>
 254       all return
 255       <span class="errorcode">LWRES_R_SUCCESS</span>
 256       on success.
 257       They return
 258       <span class="errorcode">LWRES_R_NOMEMORY</span>
 259       if memory allocation fails.
 260       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 261       is returned if the available space in the buffer
 262       <em class="parameter"><code>b</code></em>
 263       is too small to accommodate the packet header or the
 264       <span class="type">lwres_gabnrequest_t</span>
 265       and
 266       <span class="type">lwres_gabnresponse_t</span>
 267       structures.
 268       <code class="function">lwres_gabnrequest_parse()</code>
 269       and
 270       <code class="function">lwres_gabnresponse_parse()</code>
 271       will return
 272       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 273       if the buffer is not empty after decoding the received packet.
 274       These functions will return
 275       <span class="errorcode">LWRES_R_FAILURE</span>
 276       if
 277       <code class="varname">pktflags</code>
 278       in the packet header structure
 279       <span class="type">lwres_lwpacket_t</span>
 280       indicate that the packet is not a response to an earlier query.
 281     </p>
 282 </div>
 283 <div class="refsection">
 284 <a name="id-1.9"></a><h2>SEE ALSO</h2>
 285 <p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>
 286     </p>
 287 </div>
 288 </div></body>
 289 </html>