/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">
  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="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">
  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. 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. <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>.
  254. </p>
  255. </div>
  256. </div></body>
  257. </html>