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

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 262 lines · 246 code · 16 blank · 0 comment · 0 complexity · 7f594ff4071c8a2dcd9a804d5640853a MD5 · raw file

  1. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  2. "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
  3. [<!ENTITY mdash "&#8212;">]>
  4. <!--
  5. - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
  6. - Copyright (C) 2000, 2001 Internet Software Consortium.
  7. -
  8. - Permission to use, copy, modify, and/or distribute this software for any
  9. - purpose with or without fee is hereby granted, provided that the above
  10. - copyright notice and this permission notice appear in all copies.
  11. -
  12. - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  13. - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  14. - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  15. - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  16. - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  17. - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  18. - PERFORMANCE OF THIS SOFTWARE.
  19. -->
  20. <!-- $Id$ -->
  21. <refentry>
  22. <refentryinfo>
  23. <date>Jun 30, 2000</date>
  24. </refentryinfo>
  25. <refmeta>
  26. <refentrytitle>lwres_gnba</refentrytitle>
  27. <manvolnum>3</manvolnum>
  28. <refmiscinfo>BIND9</refmiscinfo>
  29. </refmeta>
  30. <docinfo>
  31. <copyright>
  32. <year>2004</year>
  33. <year>2005</year>
  34. <year>2007</year>
  35. <year>2012</year>
  36. <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  37. </copyright>
  38. <copyright>
  39. <year>2000</year>
  40. <year>2001</year>
  41. <holder>Internet Software Consortium.</holder>
  42. </copyright>
  43. </docinfo>
  44. <refnamediv>
  45. <refname>lwres_gnbarequest_render</refname>
  46. <refname>lwres_gnbaresponse_render</refname>
  47. <refname>lwres_gnbarequest_parse</refname>
  48. <refname>lwres_gnbaresponse_parse</refname>
  49. <refname>lwres_gnbaresponse_free</refname>
  50. <refname>lwres_gnbarequest_free</refname>
  51. <refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose>
  52. </refnamediv>
  53. <refsynopsisdiv>
  54. <funcsynopsis>
  55. <funcsynopsisinfo>
  56. #include &lt;lwres/lwres.h&gt;
  57. </funcsynopsisinfo>
  58. <funcprototype>
  59. <funcdef>
  60. lwres_result_t
  61. <function>lwres_gnbarequest_render</function>
  62. </funcdef>
  63. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  64. <paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef>
  65. <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  66. <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  67. </funcprototype>
  68. <funcprototype>
  69. <funcdef>
  70. lwres_result_t
  71. <function>lwres_gnbaresponse_render</function>
  72. </funcdef>
  73. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  74. <paramdef>lwres_gnbaresponse_t *<parameter>req</parameter></paramdef>
  75. <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  76. <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  77. </funcprototype>
  78. <funcprototype>
  79. <funcdef>
  80. lwres_result_t
  81. <function>lwres_gnbarequest_parse</function></funcdef>
  82. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  83. <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  84. <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  85. <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>
  86. </funcprototype>
  87. <funcprototype>
  88. <funcdef>
  89. lwres_result_t
  90. <function>lwres_gnbaresponse_parse</function></funcdef>
  91. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  92. <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  93. <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  94. <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
  95. </funcprototype>
  96. <funcprototype>
  97. <funcdef>
  98. void
  99. <function>lwres_gnbaresponse_free</function>
  100. </funcdef>
  101. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  102. <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
  103. </funcprototype>
  104. <funcprototype>
  105. <funcdef>
  106. void
  107. <function>lwres_gnbarequest_free</function></funcdef>
  108. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  109. <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>
  110. </funcprototype>
  111. </funcsynopsis>
  112. </refsynopsisdiv>
  113. <refsect1>
  114. <title>DESCRIPTION</title>
  115. <para>
  116. These are low-level routines for creating and parsing
  117. lightweight resolver address-to-name lookup request and
  118. response messages.
  119. </para>
  120. <para>
  121. There are four main functions for the getnamebyaddr opcode.
  122. One render function converts a getnamebyaddr request structure &mdash;
  123. <type>lwres_gnbarequest_t</type> &mdash;
  124. to the lightweight resolver's canonical format.
  125. It is complemented by a parse function that converts a packet in this
  126. canonical format to a getnamebyaddr request structure.
  127. Another render function converts the getnamebyaddr response structure
  128. &mdash;
  129. <type>lwres_gnbaresponse_t</type>
  130. to the canonical format.
  131. This is complemented by a parse function which converts a packet in
  132. canonical format to a getnamebyaddr response structure.
  133. </para>
  134. <para>
  135. These structures are defined in
  136. <filename>lwres/lwres.h</filename>.
  137. They are shown below.
  138. </para>
  139. <para><programlisting>
  140. #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
  141. </programlisting>
  142. </para>
  143. <para><programlisting>
  144. typedef struct {
  145. lwres_uint32_t flags;
  146. lwres_addr_t addr;
  147. } lwres_gnbarequest_t;
  148. </programlisting>
  149. </para>
  150. <para><programlisting>
  151. typedef struct {
  152. lwres_uint32_t flags;
  153. lwres_uint16_t naliases;
  154. char *realname;
  155. char **aliases;
  156. lwres_uint16_t realnamelen;
  157. lwres_uint16_t *aliaslen;
  158. void *base;
  159. size_t baselen;
  160. } lwres_gnbaresponse_t;
  161. </programlisting>
  162. </para>
  163. <para><function>lwres_gnbarequest_render()</function>
  164. uses resolver context <varname>ctx</varname> to convert
  165. getnamebyaddr request structure <varname>req</varname> to
  166. canonical format. The packet header structure
  167. <varname>pkt</varname> is initialised and transferred to buffer
  168. <varname>b</varname>. The contents of <varname>*req</varname>
  169. are then appended to the buffer in canonical format.
  170. <function>lwres_gnbaresponse_render()</function> performs the
  171. same task, except it converts a getnamebyaddr response structure
  172. <type>lwres_gnbaresponse_t</type> to the lightweight resolver's
  173. canonical format.
  174. </para>
  175. <para><function>lwres_gnbarequest_parse()</function>
  176. uses context <varname>ctx</varname> to convert the contents of
  177. packet <varname>pkt</varname> to a
  178. <type>lwres_gnbarequest_t</type> structure. Buffer
  179. <varname>b</varname> provides space to be used for storing this
  180. structure. When the function succeeds, the resulting
  181. <type>lwres_gnbarequest_t</type> is made available through
  182. <varname>*structp</varname>.
  183. <function>lwres_gnbaresponse_parse()</function> offers the same
  184. semantics as <function>lwres_gnbarequest_parse()</function>
  185. except it yields a <type>lwres_gnbaresponse_t</type> structure.
  186. </para>
  187. <para><function>lwres_gnbaresponse_free()</function>
  188. and <function>lwres_gnbarequest_free()</function> release the
  189. memory in resolver context <varname>ctx</varname> that was
  190. allocated to the <type>lwres_gnbaresponse_t</type> or
  191. <type>lwres_gnbarequest_t</type> structures referenced via
  192. <varname>structp</varname>. Any memory associated with
  193. ancillary buffers and strings for those structures is also
  194. discarded.
  195. </para>
  196. </refsect1>
  197. <refsect1>
  198. <title>RETURN VALUES</title>
  199. <para>
  200. The getnamebyaddr opcode functions
  201. <function>lwres_gnbarequest_render()</function>,
  202. <function>lwres_gnbaresponse_render()</function>
  203. <function>lwres_gnbarequest_parse()</function>
  204. and
  205. <function>lwres_gnbaresponse_parse()</function>
  206. all return
  207. <errorcode>LWRES_R_SUCCESS</errorcode>
  208. on success.
  209. They return
  210. <errorcode>LWRES_R_NOMEMORY</errorcode>
  211. if memory allocation fails.
  212. <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
  213. is returned if the available space in the buffer
  214. <varname>b</varname>
  215. is too small to accommodate the packet header or the
  216. <type>lwres_gnbarequest_t</type>
  217. and
  218. <type>lwres_gnbaresponse_t</type>
  219. structures.
  220. <function>lwres_gnbarequest_parse()</function>
  221. and
  222. <function>lwres_gnbaresponse_parse()</function>
  223. will return
  224. <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
  225. if the buffer is not empty after decoding the received packet.
  226. These functions will return
  227. <errorcode>LWRES_R_FAILURE</errorcode>
  228. if
  229. <structfield>pktflags</structfield>
  230. in the packet header structure
  231. <type>lwres_lwpacket_t</type>
  232. indicate that the packet is not a response to an earlier query.
  233. </para>
  234. </refsect1>
  235. <refsect1>
  236. <title>SEE ALSO</title>
  237. <para><citerefentry>
  238. <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
  239. </citerefentry>.
  240. </para>
  241. </refsect1>
  242. </refentry><!--
  243. - Local variables:
  244. - mode: sgml
  245. - End:
  246. -->