external/bsd/bind/dist/lib/lwres/man/lwres_resutil.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_resutil</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_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr &#8212; lightweight resolver utility functions</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_string_parse</b>(</code></td>
  39 <td>lwres_buffer_t * </td>
  40 <td>
  41 <var class="pdparam">b</var>, </td>
  42 </tr>
  43 <tr>
  44 <td> </td>
  45 <td>char ** </td>
  46 <td>
  47 <var class="pdparam">c</var>, </td>
  48 </tr>
  49 <tr>
  50 <td> </td>
  51 <td>lwres_uint16_t * </td>
  52 <td>
  53 <var class="pdparam">len</var><code>)</code>;</td>
  54 </tr>
  55 </table>
  56 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  57 <tr>
  58 <td><code class="funcdef">
  59 lwres_result_t
  60 <b class="fsfunc">lwres_addr_parse</b>(</code></td>
  61 <td>lwres_buffer_t * </td>
  62 <td>
  63 <var class="pdparam">b</var>, </td>
  64 </tr>
  65 <tr>
  66 <td> </td>
  67 <td>lwres_addr_t * </td>
  68 <td>
  69 <var class="pdparam">addr</var><code>)</code>;</td>
  70 </tr>
  71 </table>
  72 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  73 <tr>
  74 <td><code class="funcdef">
  75 lwres_result_t
  76 <b class="fsfunc">lwres_getaddrsbyname</b>(</code></td>
  77 <td>lwres_context_t * </td>
  78 <td>
  79 <var class="pdparam">ctx</var>, </td>
  80 </tr>
  81 <tr>
  82 <td> </td>
  83 <td>const char * </td>
  84 <td>
  85 <var class="pdparam">name</var>, </td>
  86 </tr>
  87 <tr>
  88 <td> </td>
  89 <td>lwres_uint32_t  </td>
  90 <td>
  91 <var class="pdparam">addrtypes</var>, </td>
  92 </tr>
  93 <tr>
  94 <td> </td>
  95 <td>lwres_gabnresponse_t ** </td>
  96 <td>
  97 <var class="pdparam">structp</var><code>)</code>;</td>
  98 </tr>
  99 </table>
 100 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
 101 <tr>
 102 <td><code class="funcdef">
 103 lwres_result_t
 104 <b class="fsfunc">lwres_getnamebyaddr</b>(</code></td>
 105 <td>lwres_context_t * </td>
 106 <td>
 107 <var class="pdparam">ctx</var>, </td>
 108 </tr>
 109 <tr>
 110 <td> </td>
 111 <td>lwres_uint32_t  </td>
 112 <td>
 113 <var class="pdparam">addrtype</var>, </td>
 114 </tr>
 115 <tr>
 116 <td> </td>
 117 <td>lwres_uint16_t  </td>
 118 <td>
 119 <var class="pdparam">addrlen</var>, </td>
 120 </tr>
 121 <tr>
 122 <td> </td>
 123 <td>const unsigned char * </td>
 124 <td>
 125 <var class="pdparam">addr</var>, </td>
 126 </tr>
 127 <tr>
 128 <td> </td>
 129 <td>lwres_gnbaresponse_t ** </td>
 130 <td>
 131 <var class="pdparam">structp</var><code>)</code>;</td>
 132 </tr>
 133 </table>
 134 </div>
 135 </div>
 136 <div class="refsect1" lang="en">
 137 <a name="id2543476"></a><h2>DESCRIPTION</h2>
 138 <p><code class="function">lwres_string_parse()</code>
 139       retrieves a DNS-encoded string starting the current pointer of
 140       lightweight resolver buffer <em class="parameter"><code>b</code></em>: i.e.
 141       <code class="constant">b-&gt;current</code>.  When the function returns,
 142       the address of the first byte of the encoded string is returned
 143       via <em class="parameter"><code>*c</code></em> and the length of that string is
 144       given by <em class="parameter"><code>*len</code></em>.  The buffer's current
 145       pointer is advanced to point at the character following the
 146       string length, the encoded string, and the trailing
 147       <span class="type">NULL</span> character.
 148     </p>
 149 <p><code class="function">lwres_addr_parse()</code>
 150       extracts an address from the buffer <em class="parameter"><code>b</code></em>.
 151       The buffer's current pointer <code class="constant">b-&gt;current</code>
 152       is presumed to point at an encoded address: the address preceded
 153       by a 32-bit protocol family identifier and a 16-bit length
 154       field.  The encoded address is copied to
 155       <code class="constant">addr-&gt;address</code> and
 156       <code class="constant">addr-&gt;length</code> indicates the size in bytes
 157       of the address that was copied.
 158       <code class="constant">b-&gt;current</code> is advanced to point at the
 159       next byte of available data in the buffer following the encoded
 160       address.
 161     </p>
 162 <p><code class="function">lwres_getaddrsbyname()</code>
 163       and <code class="function">lwres_getnamebyaddr()</code> use the
 164       <span class="type">lwres_gnbaresponse_t</span> structure defined below:
 165     </p>
 166 <pre class="programlisting">
 167 typedef struct {
 168         lwres_uint32_t          flags;
 169         lwres_uint16_t          naliases;
 170         lwres_uint16_t          naddrs;
 171         char                   *realname;
 172         char                  **aliases;
 173         lwres_uint16_t          realnamelen;
 174         lwres_uint16_t         *aliaslen;
 175         lwres_addrlist_t        addrs;
 176         void                   *base;
 177         size_t                  baselen;
 178 } lwres_gabnresponse_t;
 179 </pre>
 180 <p>
 181       The contents of this structure are not manipulated directly but
 182       they are controlled through the
 183       <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>
 184       functions.
 185     </p>
 186 <p>
 187       The lightweight resolver uses
 188       <code class="function">lwres_getaddrsbyname()</code> to perform
 189       forward lookups.
 190       Hostname <em class="parameter"><code>name</code></em> is looked up using the
 191       resolver
 192       context <em class="parameter"><code>ctx</code></em> for memory allocation.
 193       <em class="parameter"><code>addrtypes</code></em> is a bitmask indicating
 194       which type of
 195       addresses are to be looked up.  Current values for this bitmask are
 196       <span class="type">LWRES_ADDRTYPE_V4</span> for IPv4 addresses and
 197       <span class="type">LWRES_ADDRTYPE_V6</span> for IPv6 addresses.  Results of the
 198       lookup are returned in <em class="parameter"><code>*structp</code></em>.
 199     </p>
 200 <p><code class="function">lwres_getnamebyaddr()</code>
 201       performs reverse lookups.  Resolver context
 202       <em class="parameter"><code>ctx</code></em> is used for memory allocation.  The
 203       address type is indicated by <em class="parameter"><code>addrtype</code></em>:
 204       <span class="type">LWRES_ADDRTYPE_V4</span> or
 205       <span class="type">LWRES_ADDRTYPE_V6</span>.  The address to be looked up is
 206       given by <em class="parameter"><code>addr</code></em> and its length is
 207       <em class="parameter"><code>addrlen</code></em> bytes.  The result of the
 208       function call is made available through
 209       <em class="parameter"><code>*structp</code></em>.
 210     </p>
 211 </div>
 212 <div class="refsect1" lang="en">
 213 <a name="id2543614"></a><h2>RETURN VALUES</h2>
 214 <p>
 215       Successful calls to
 216       <code class="function">lwres_string_parse()</code>
 217       and
 218       <code class="function">lwres_addr_parse()</code>
 219       return
 220       <span class="errorcode">LWRES_R_SUCCESS.</span>
 221       Both functions return
 222       <span class="errorcode">LWRES_R_FAILURE</span>
 223       if the buffer is corrupt or
 224       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 225       if the buffer has less space than expected for the components of the
 226       encoded string or address.
 227     </p>
 228 <p><code class="function">lwres_getaddrsbyname()</code>
 229       returns <span class="errorcode">LWRES_R_SUCCESS</span> on success and it
 230       returns <span class="errorcode">LWRES_R_NOTFOUND</span> if the hostname
 231       <em class="parameter"><code>name</code></em> could not be found.
 232     </p>
 233 <p><span class="errorcode">LWRES_R_SUCCESS</span>
 234       is returned by a successful call to
 235       <code class="function">lwres_getnamebyaddr()</code>.
 236     </p>
 237 <p>
 238       Both
 239       <code class="function">lwres_getaddrsbyname()</code>
 240       and
 241       <code class="function">lwres_getnamebyaddr()</code>
 242       return
 243       <span class="errorcode">LWRES_R_NOMEMORY</span>
 244       when memory allocation requests fail and
 245       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 246       if the buffers used for sending queries and receiving replies are too
 247       small.
 248     </p>
 249 </div>
 250 <div class="refsect1" lang="en">
 251 <a name="id2543686"></a><h2>SEE ALSO</h2>
 252 <p><span class="citerefentry"><span class="refentrytitle">lwres_buffer</span>(3)</span>,
 253
 254       <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>.
 255     </p>
 256 </div>
 257 </div></body>
 258 </html>