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

https://bitbucket.org/freebsd/freebsd-head/ · HTML · 324 lines · 304 code · 3 blank · 17 comment · 0 complexity · 6a51675abdb0c0fde5c7b5dd65a44877 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_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="id2543526"></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 lighweight 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. The contents of <em class="parameter"><code>*req</code></em> are then appended to
  249. the buffer in canonical format.
  250. <code class="function">lwres_gabnresponse_render()</code> performs the
  251. same task, except it converts a getaddrbyname response structure
  252. <span class="type">lwres_gabnresponse_t</span> to the lightweight resolver's
  253. canonical format.
  254. </p>
  255. <p><code class="function">lwres_gabnrequest_parse()</code>
  256. uses context <em class="parameter"><code>ctx</code></em> to convert the contents
  257. of packet <em class="parameter"><code>pkt</code></em> to a
  258. <span class="type">lwres_gabnrequest_t</span> structure. Buffer
  259. <em class="parameter"><code>b</code></em> provides space to be used for storing
  260. this structure. When the function succeeds, the resulting
  261. <span class="type">lwres_gabnrequest_t</span> is made available through
  262. <em class="parameter"><code>*structp</code></em>.
  263. <code class="function">lwres_gabnresponse_parse()</code> offers the same
  264. semantics as <code class="function">lwres_gabnrequest_parse()</code>
  265. except it yields a <span class="type">lwres_gabnresponse_t</span> structure.
  266. </p>
  267. <p><code class="function">lwres_gabnresponse_free()</code>
  268. and <code class="function">lwres_gabnrequest_free()</code> release the
  269. memory in resolver context <em class="parameter"><code>ctx</code></em> that was
  270. allocated to the <span class="type">lwres_gabnresponse_t</span> or
  271. <span class="type">lwres_gabnrequest_t</span> structures referenced via
  272. <em class="parameter"><code>structp</code></em>.
  273. Any memory associated with ancillary buffers and strings for
  274. those structures is also discarded.
  275. </p>
  276. </div>
  277. <div class="refsect1" lang="en">
  278. <a name="id2543671"></a><h2>RETURN VALUES</h2>
  279. <p>
  280. The getaddrbyname opcode functions
  281. <code class="function">lwres_gabnrequest_render()</code>,
  282. <code class="function">lwres_gabnresponse_render()</code>
  283. <code class="function">lwres_gabnrequest_parse()</code>
  284. and
  285. <code class="function">lwres_gabnresponse_parse()</code>
  286. all return
  287. <span class="errorcode">LWRES_R_SUCCESS</span>
  288. on success.
  289. They return
  290. <span class="errorcode">LWRES_R_NOMEMORY</span>
  291. if memory allocation fails.
  292. <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
  293. is returned if the available space in the buffer
  294. <em class="parameter"><code>b</code></em>
  295. is too small to accommodate the packet header or the
  296. <span class="type">lwres_gabnrequest_t</span>
  297. and
  298. <span class="type">lwres_gabnresponse_t</span>
  299. structures.
  300. <code class="function">lwres_gabnrequest_parse()</code>
  301. and
  302. <code class="function">lwres_gabnresponse_parse()</code>
  303. will return
  304. <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
  305. if the buffer is not empty after decoding the received packet.
  306. These functions will return
  307. <span class="errorcode">LWRES_R_FAILURE</span>
  308. if
  309. <em class="structfield"><code>pktflags</code></em>
  310. in the packet header structure
  311. <span class="type">lwres_lwpacket_t</span>
  312. indicate that the packet is not a response to an earlier query.
  313. </p>
  314. </div>
  315. <div class="refsect1" lang="en">
  316. <a name="id2543737"></a><h2>SEE ALSO</h2>
  317. <p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>
  318. </p>
  319. </div>
  320. </div></body>
  321. </html>