external/bsd/bind/dist/lib/lwres/man/lwres_getrrsetbyname.html

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007, 2014 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="id2543424"></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
 141       Memory allocated for the dynamically allocated structures
 142       created by a successful call to
 143       <code class="function">lwres_getrrsetbyname()</code> is released by
 144       <code class="function">lwres_freerrset()</code>.
 145
 146       <em class="parameter"><code>rrset</code></em> is a pointer to a <span class="type">struct
 147       rrset</span> created by a call to
 148       <code class="function">lwres_getrrsetbyname()</code>.
 149     </p>
 150 <p></p>
 151 </div>
 152 <div class="refsect1" lang="en">
 153 <a name="id2543536"></a><h2>RETURN VALUES</h2>
 154 <p><code class="function">lwres_getrrsetbyname()</code>
 155       returns zero on success, and one of the following error codes if
 156       an error occurred:
 157       </p>
 158 <div class="variablelist"><dl>
 159 <dt><span class="term"><code class="constant">ERRSET_NONAME</code></span></dt>
 160 <dd><p>
 161               the name does not exist
 162             </p></dd>
 163 <dt><span class="term"><code class="constant">ERRSET_NODATA</code></span></dt>
 164 <dd><p>
 165               the name exists, but does not have data of the desired type
 166             </p></dd>
 167 <dt><span class="term"><code class="constant">ERRSET_NOMEMORY</code></span></dt>
 168 <dd><p>
 169               memory could not be allocated
 170             </p></dd>
 171 <dt><span class="term"><code class="constant">ERRSET_INVAL</code></span></dt>
 172 <dd><p>
 173               a parameter is invalid
 174             </p></dd>
 175 <dt><span class="term"><code class="constant">ERRSET_FAIL</code></span></dt>
 176 <dd><p>
 177               other failure
 178             </p></dd>
 179 <dt><span class="term"><code class="constant"></code></span></dt>
 180 <dd><p></p></dd>
 181 </dl></div>
 182 <p>
 183
 184     </p>
 185 </div>
 186 <div class="refsect1" lang="en">
 187 <a name="id2543636"></a><h2>SEE ALSO</h2>
 188 <p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>.
 189     </p>
 190 </div>
 191 </div></body>
 192 </html>