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