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

https://bitbucket.org/freebsd/freebsd-head/ · HTML · 192 lines · 172 code · 3 blank · 17 comment · 0 complexity · a9b4fffe46e4f265fd6d7f669d7e62cd 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_getrrsetbyname</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_getrrsetbyname, lwres_freerrset &#8212; retrieve DNS records</p>
  29. </div>
  30. <div class="refsynopsisdiv">
  31. <h2>Synopsis</h2>
  32. <div class="funcsynopsis">
  33. <pre class="funcsynopsisinfo">#include &lt;lwres/netdb.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. int
  38. <b class="fsfunc">lwres_getrrsetbyname</b>(</code></td>
  39. <td>const char * </td>
  40. <td>
  41. <var class="pdparam">hostname</var>, </td>
  42. </tr>
  43. <tr>
  44. <td> </td>
  45. <td>unsigned int  </td>
  46. <td>
  47. <var class="pdparam">rdclass</var>, </td>
  48. </tr>
  49. <tr>
  50. <td> </td>
  51. <td>unsigned int  </td>
  52. <td>
  53. <var class="pdparam">rdtype</var>, </td>
  54. </tr>
  55. <tr>
  56. <td> </td>
  57. <td>unsigned int  </td>
  58. <td>
  59. <var class="pdparam">flags</var>, </td>
  60. </tr>
  61. <tr>
  62. <td> </td>
  63. <td>struct rrsetinfo ** </td>
  64. <td>
  65. <var class="pdparam">res</var><code>)</code>;</td>
  66. </tr>
  67. </table>
  68. <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr>
  69. <td><code class="funcdef">
  70. void
  71. <b class="fsfunc">lwres_freerrset</b>(</code></td>
  72. <td>struct rrsetinfo * </td>
  73. <td>
  74. <var class="pdparam">rrset</var><code>)</code>;</td>
  75. </tr></table>
  76. </div>
  77. <p>
  78. The following structures are used:
  79. </p>
  80. <pre class="programlisting">
  81. struct rdatainfo {
  82. unsigned int rdi_length; /* length of data */
  83. unsigned char *rdi_data; /* record data */
  84. };
  85. </pre>
  86. <p>
  87. </p>
  88. <pre class="programlisting">
  89. struct rrsetinfo {
  90. unsigned int rri_flags; /* RRSET_VALIDATED... */
  91. unsigned int rri_rdclass; /* class number */
  92. unsigned int rri_rdtype; /* RR type number */
  93. unsigned int rri_ttl; /* time to live */
  94. unsigned int rri_nrdatas; /* size of rdatas array */
  95. unsigned int rri_nsigs; /* size of sigs array */
  96. char *rri_name; /* canonical name */
  97. struct rdatainfo *rri_rdatas; /* individual records */
  98. struct rdatainfo *rri_sigs; /* individual signatures */
  99. };
  100. </pre>
  101. <p>
  102. </p>
  103. </div>
  104. <div class="refsect1" lang="en">
  105. <a name="id2543418"></a><h2>DESCRIPTION</h2>
  106. <p><code class="function">lwres_getrrsetbyname()</code>
  107. gets a set of resource records associated with a
  108. <em class="parameter"><code>hostname</code></em>, <em class="parameter"><code>class</code></em>,
  109. and <em class="parameter"><code>type</code></em>.
  110. <em class="parameter"><code>hostname</code></em> is a pointer a to
  111. null-terminated string. The <em class="parameter"><code>flags</code></em> field
  112. is currently unused and must be zero.
  113. </p>
  114. <p>
  115. After a successful call to
  116. <code class="function">lwres_getrrsetbyname()</code>,
  117. <em class="parameter"><code>*res</code></em> is a pointer to an
  118. <span class="type">rrsetinfo</span> structure, containing a list of one or
  119. more <span class="type">rdatainfo</span> structures containing resource
  120. records and potentially another list of <span class="type">rdatainfo</span>
  121. structures containing SIG resource records associated with those
  122. records. The members <code class="constant">rri_rdclass</code> and
  123. <code class="constant">rri_rdtype</code> are copied from the parameters.
  124. <code class="constant">rri_ttl</code> and <code class="constant">rri_name</code>
  125. are properties of the obtained rrset. The resource records
  126. contained in <code class="constant">rri_rdatas</code> and
  127. <code class="constant">rri_sigs</code> are in uncompressed DNS wire
  128. format. Properties of the rdataset are represented in the
  129. <code class="constant">rri_flags</code> bitfield. If the RRSET_VALIDATED
  130. bit is set, the data has been DNSSEC validated and the
  131. signatures verified.
  132. </p>
  133. <p>
  134. All of the information returned by
  135. <code class="function">lwres_getrrsetbyname()</code> is dynamically
  136. allocated: the <code class="constant">rrsetinfo</code> and
  137. <code class="constant">rdatainfo</code> structures, and the canonical
  138. host name strings pointed to by the
  139. <code class="constant">rrsetinfo</code>structure.
  140. Memory allocated for the dynamically allocated structures
  141. created by a successful call to
  142. <code class="function">lwres_getrrsetbyname()</code> is released by
  143. <code class="function">lwres_freerrset()</code>.
  144. <em class="parameter"><code>rrset</code></em> is a pointer to a <span class="type">struct
  145. rrset</span> created by a call to
  146. <code class="function">lwres_getrrsetbyname()</code>.
  147. </p>
  148. <p></p>
  149. </div>
  150. <div class="refsect1" lang="en">
  151. <a name="id2543530"></a><h2>RETURN VALUES</h2>
  152. <p><code class="function">lwres_getrrsetbyname()</code>
  153. returns zero on success, and one of the following error codes if
  154. an error occurred:
  155. </p>
  156. <div class="variablelist"><dl>
  157. <dt><span class="term"><code class="constant">ERRSET_NONAME</code></span></dt>
  158. <dd><p>
  159. the name does not exist
  160. </p></dd>
  161. <dt><span class="term"><code class="constant">ERRSET_NODATA</code></span></dt>
  162. <dd><p>
  163. the name exists, but does not have data of the desired type
  164. </p></dd>
  165. <dt><span class="term"><code class="constant">ERRSET_NOMEMORY</code></span></dt>
  166. <dd><p>
  167. memory could not be allocated
  168. </p></dd>
  169. <dt><span class="term"><code class="constant">ERRSET_INVAL</code></span></dt>
  170. <dd><p>
  171. a parameter is invalid
  172. </p></dd>
  173. <dt><span class="term"><code class="constant">ERRSET_FAIL</code></span></dt>
  174. <dd><p>
  175. other failure
  176. </p></dd>
  177. <dt><span class="term"><code class="constant"></code></span></dt>
  178. <dd><p></p></dd>
  179. </dl></div>
  180. <p>
  181. </p>
  182. </div>
  183. <div class="refsect1" lang="en">
  184. <a name="id2543630"></a><h2>SEE ALSO</h2>
  185. <p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>.
  186. </p>
  187. </div>
  188. </div></body>
  189. </html>