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