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

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