PageRenderTime 108ms CodeModel.GetById 99ms app.highlight 5ms RepoModel.GetById 2ms app.codeStats 0ms

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

https://bitbucket.org/freebsd/freebsd-head/
HTML | 258 lines | 240 code | 1 blank | 17 comment | 0 complexity | 59fbf9d45aa92c722f61cc1607a54cb6 MD5 | raw file
  1<!--
  2 - Copyright (C) 2004, 2005, 2007, 2012 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">
 37lwres_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">
 59lwres_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">
 75lwres_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">
103lwres_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="id2543470"></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">
167typedef 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      foward 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="id2543609"></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="id2543681"></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>