Merge from vendor branch BZIP:
[dragonfly.git] / contrib / bind-9.3 / lib / lwres / man / lwres_getrrsetbyname.html
1 <!--
2  - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
3  - Copyright (C) 2000, 2001 Internet Software Consortium.
4  - 
5  - Permission to use, copy, modify, and 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.5.2.1.4.11 2006/06/29 13:02:31 marka 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.70.1">
23 </head>
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="id2482688"></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> </td>
40 <td>, </td>
41 </tr>
42 <tr>
43 <td> </td>
44 <td> </td>
45 <td>, </td>
46 </tr>
47 <tr>
48 <td> </td>
49 <td> </td>
50 <td>, </td>
51 </tr>
52 <tr>
53 <td> </td>
54 <td> </td>
55 <td>, </td>
56 </tr>
57 <tr>
58 <td> </td>
59 <td> </td>
60 <td>, </td>
61 </tr>
62 <tr>
63 <td> </td>
64 <td> </td>
65 <td>
66 <code>)</code>;</td>
67 </tr>
68 </table>
69 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
70 <tr>
71 <td><code class="funcdef">
72 void
73 <b class="fsfunc">lwres_freerrset</b>(</code></td>
74 <td> </td>
75 <td>
76 <code>)</code>;</td>
77 </tr>
78 <tr>
79 <td> </td>
80 <td> </td>
81 <td>
82 <code>)</code>;</td>
83 </tr>
84 </table>
85 </div>
86 <p>
87 The following structures are used:
88 </p>
89 <pre class="programlisting">
90 struct  rdatainfo {
91         unsigned int            rdi_length;     /* length of data */
92         unsigned char           *rdi_data;      /* record data */
93 };
94
95 struct  rrsetinfo {
96         unsigned int            rri_flags;      /* RRSET_VALIDATED... */
97         unsigned int            rri_rdclass;    /* class number */
98         unsigned int            rri_rdtype;     /* RR type number */
99         unsigned int            rri_ttl;        /* time to live */
100         unsigned int            rri_nrdatas;    /* size of rdatas array */
101         unsigned int            rri_nsigs;      /* size of sigs array */
102         char                    *rri_name;      /* canonical name */
103         struct rdatainfo        *rri_rdatas;    /* individual records */
104         struct rdatainfo        *rri_sigs;      /* individual signatures */
105 };
106 </pre>
107 <p>
108 </p>
109 </div>
110 <div class="refsect1" lang="en">
111 <a name="id2549443"></a><h2>DESCRIPTION</h2>
112 <p>
113 <code class="function">lwres_getrrsetbyname()</code>
114 gets a set of resource records associated with a
115 <em class="parameter"><code>hostname</code></em>,
116
117 <em class="parameter"><code>class</code></em>,
118
119 and
120 <em class="parameter"><code>type</code></em>.
121
122 <em class="parameter"><code>hostname</code></em>
123 is
124 a pointer a to null-terminated string.  The
125 <em class="parameter"><code>flags</code></em>
126 field is currently unused and must be zero.
127 </p>
128 <p>
129 After a successful call to
130 <code class="function">lwres_getrrsetbyname()</code>,
131
132 <em class="parameter"><code>*res</code></em>
133 is a pointer to an
134 <span class="type">rrsetinfo</span>
135 structure, containing a list of one or more
136 <span class="type">rdatainfo</span>
137 structures containing resource records and potentially another list of
138 <span class="type">rdatainfo</span>
139 structures containing SIG resource records
140 associated with those records.
141 The members
142 <code class="constant">rri_rdclass</code>
143 and
144 <code class="constant">rri_rdtype</code>
145 are copied from the parameters.
146 <code class="constant">rri_ttl</code>
147 and
148 <code class="constant">rri_name</code>
149 are properties of the obtained rrset.
150 The resource records contained in
151 <code class="constant">rri_rdatas</code>
152 and
153 <code class="constant">rri_sigs</code>
154 are in uncompressed DNS wire format.
155 Properties of the rdataset are represented in the
156 <code class="constant">rri_flags</code>
157 bitfield.  If the RRSET_VALIDATED bit is set, the data has been DNSSEC
158 validated and the signatures verified.  
159 </p>
160 <p>
161 All of the information returned by
162 <code class="function">lwres_getrrsetbyname()</code>
163 is dynamically allocated: the
164 <code class="constant">rrsetinfo</code>
165 and
166 <code class="constant">rdatainfo</code>
167 structures,
168 and the canonical host name strings pointed to by the
169 <code class="constant">rrsetinfo</code>structure.
170
171 Memory allocated for the dynamically allocated structures created by
172 a successful call to
173 <code class="function">lwres_getrrsetbyname()</code>
174 is released by
175 <code class="function">lwres_freerrset()</code>.
176
177 <em class="parameter"><code>rrset</code></em>
178 is a pointer to a
179 <span class="type">struct rrset</span>
180 created by a call to
181 <code class="function">lwres_getrrsetbyname()</code>.
182
183 </p>
184 <p>
185 </p>
186 </div>
187 <div class="refsect1" lang="en">
188 <a name="id2549623"></a><h2>RETURN VALUES</h2>
189 <p>
190 <code class="function">lwres_getrrsetbyname()</code>
191 returns zero on success, and one of the following error
192 codes if an error occurred:
193 </p>
194 <div class="variablelist"><dl>
195 <dt><span class="term"><code class="constant">ERRSET_NONAME</code></span></dt>
196 <dd><p>
197 the name does not exist
198 </p></dd>
199 <dt><span class="term"><code class="constant">ERRSET_NODATA</code></span></dt>
200 <dd><p>
201 the name exists, but does not have data of the desired type
202 </p></dd>
203 <dt><span class="term"><code class="constant">ERRSET_NOMEMORY</code></span></dt>
204 <dd><p>
205 memory could not be allocated
206 </p></dd>
207 <dt><span class="term"><code class="constant">ERRSET_INVAL</code></span></dt>
208 <dd><p>
209 a parameter is invalid
210 </p></dd>
211 <dt><span class="term"><code class="constant">ERRSET_FAIL</code></span></dt>
212 <dd><p>
213 other failure
214 </p></dd>
215 <dt><span class="term"><code class="constant"></code></span></dt>
216 <dd><p>
217 </p></dd>
218 </dl></div>
219 <p>
220
221 </p>
222 </div>
223 <div class="refsect1" lang="en">
224 <a name="id2549697"></a><h2>SEE ALSO</h2>
225 <p>
226 <span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>.
227 </p>
228 </div>
229 </div></body>
230 </html>