BIND: update vendor tree to 9.5.2-P2
[dragonfly.git] / contrib / bind / lib / lwres / man / lwres_getrrsetbyname.html
1 <!--
2  - Copyright (C) 2004, 2005, 2007 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: lwres_getrrsetbyname.html,v 1.23.214.1.2.1 2009/12/31 23:47:14 tbox Exp $ -->
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="id2476267"></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="id2543412"></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="id2543524"></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="id2543624"></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>