Merge from vendor branch BZIP:
[dragonfly.git] / contrib / bind-9.3 / lib / lwres / man / lwres_gnba.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_gnba.html,v 1.6.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_gnba</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_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free &#8212; lightweight resolver getnamebyaddress message handling</p>
29 </div>
30 <div class="refsynopsisdiv">
31 <h2>Synopsis</h2>
32 <div class="funcsynopsis">
33 <pre class="funcsynopsisinfo">
34 #include &lt;lwres/lwres.h&gt;
35 </pre>
36 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
37 <tr>
38 <td><code class="funcdef">
39 lwres_result_t
40 <b class="fsfunc">lwres_gnbarequest_render</b>
41 (</code></td>
42 <td> </td>
43 <td>
44 <var class="pdparam">ctx</var>, </td>
45 </tr>
46 <tr>
47 <td> </td>
48 <td> </td>
49 <td>
50 <var class="pdparam">ctx</var>, </td>
51 </tr>
52 <tr>
53 <td> </td>
54 <td> </td>
55 <td>
56 <var class="pdparam">req</var>, </td>
57 </tr>
58 <tr>
59 <td> </td>
60 <td> </td>
61 <td>
62 <var class="pdparam">pkt</var>, </td>
63 </tr>
64 <tr>
65 <td> </td>
66 <td> </td>
67 <td>
68 <var class="pdparam">b</var><code>)</code>;</td>
69 </tr>
70 </table>
71 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
72 <tr>
73 <td><code class="funcdef">
74 lwres_result_t
75 <b class="fsfunc">lwres_gnbaresponse_render</b>
76 (</code></td>
77 <td> </td>
78 <td>, </td>
79 </tr>
80 <tr>
81 <td> </td>
82 <td> </td>
83 <td>, </td>
84 </tr>
85 <tr>
86 <td> </td>
87 <td> </td>
88 <td>, </td>
89 </tr>
90 <tr>
91 <td> </td>
92 <td> </td>
93 <td>, </td>
94 </tr>
95 <tr>
96 <td> </td>
97 <td> </td>
98 <td>
99 <code>)</code>;</td>
100 </tr>
101 </table>
102 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
103 <tr>
104 <td><code class="funcdef">
105 lwres_result_t
106 <b class="fsfunc">lwres_gnbarequest_parse</b>(</code></td>
107 <td> </td>
108 <td>, </td>
109 </tr>
110 <tr>
111 <td> </td>
112 <td> </td>
113 <td>, </td>
114 </tr>
115 <tr>
116 <td> </td>
117 <td> </td>
118 <td>, </td>
119 </tr>
120 <tr>
121 <td> </td>
122 <td> </td>
123 <td>, </td>
124 </tr>
125 <tr>
126 <td> </td>
127 <td> </td>
128 <td>
129 <code>)</code>;</td>
130 </tr>
131 </table>
132 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
133 <tr>
134 <td><code class="funcdef">
135 lwres_result_t
136 <b class="fsfunc">lwres_gnbaresponse_parse</b>(</code></td>
137 <td> </td>
138 <td>, </td>
139 </tr>
140 <tr>
141 <td> </td>
142 <td> </td>
143 <td>, </td>
144 </tr>
145 <tr>
146 <td> </td>
147 <td> </td>
148 <td>, </td>
149 </tr>
150 <tr>
151 <td> </td>
152 <td> </td>
153 <td>, </td>
154 </tr>
155 <tr>
156 <td> </td>
157 <td> </td>
158 <td>
159 <code>)</code>;</td>
160 </tr>
161 </table>
162 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
163 <tr>
164 <td><code class="funcdef">
165 void
166 <b class="fsfunc">lwres_gnbaresponse_free</b>
167 (</code></td>
168 <td> </td>
169 <td>, </td>
170 </tr>
171 <tr>
172 <td> </td>
173 <td> </td>
174 <td>, </td>
175 </tr>
176 <tr>
177 <td> </td>
178 <td> </td>
179 <td>
180 <code>)</code>;</td>
181 </tr>
182 </table>
183 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
184 <tr>
185 <td><code class="funcdef">
186 void
187 <b class="fsfunc">lwres_gnbarequest_free</b>(</code></td>
188 <td> </td>
189 <td>, </td>
190 </tr>
191 <tr>
192 <td> </td>
193 <td> </td>
194 <td>, </td>
195 </tr>
196 <tr>
197 <td> </td>
198 <td> </td>
199 <td>
200 <code>)</code>;</td>
201 </tr>
202 </table>
203 </div>
204 </div>
205 <div class="refsect1" lang="en">
206 <a name="id2549540"></a><h2>DESCRIPTION</h2>
207 <p>
208 These are low-level routines for creating and parsing
209 lightweight resolver address-to-name lookup request and 
210 response messages.
211 </p>
212 <p>
213 There are four main functions for the getnamebyaddr opcode.
214 One render function converts a getnamebyaddr request structure &#8212;
215 <span class="type">lwres_gnbarequest_t</span> &#8212;
216 to the lightweight resolver's canonical format.
217 It is complemented by a parse function that converts a packet in this
218 canonical format to a getnamebyaddr request structure.
219 Another render function converts the getnamebyaddr response structure &#8212;
220 <span class="type">lwres_gnbaresponse_t</span>
221 to the canonical format.
222 This is complemented by a parse function which converts a packet in
223 canonical format to a getnamebyaddr response structure.
224 </p>
225 <p>
226 These structures are defined in
227 <code class="filename">lwres/lwres.h</code>.
228 They are shown below.
229 </p>
230 <pre class="programlisting">
231 #define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
232
233 typedef struct {
234         lwres_uint32_t  flags;
235         lwres_addr_t    addr;
236 } lwres_gnbarequest_t;
237
238 typedef struct {
239         lwres_uint32_t  flags;
240         lwres_uint16_t  naliases;
241         char           *realname;
242         char          **aliases;
243         lwres_uint16_t  realnamelen;
244         lwres_uint16_t *aliaslen;
245         void           *base;
246         size_t          baselen;
247 } lwres_gnbaresponse_t;
248 </pre>
249 <p>
250 </p>
251 <p>
252 <code class="function">lwres_gnbarequest_render()</code>
253 uses resolver context
254 <code class="varname">ctx</code>
255 to convert getnamebyaddr request structure
256 <code class="varname">req</code>
257 to canonical format.
258 The packet header structure
259 <code class="varname">pkt</code>
260 is initialised and transferred to
261 buffer
262 <code class="varname">b</code>.
263 The contents of
264 <code class="varname">*req</code>
265 are then appended to the buffer in canonical format.
266 <code class="function">lwres_gnbaresponse_render()</code>
267 performs the same task, except it converts a getnamebyaddr response structure
268 <span class="type">lwres_gnbaresponse_t</span>
269 to the lightweight resolver's canonical format.
270 </p>
271 <p>
272 <code class="function">lwres_gnbarequest_parse()</code>
273 uses context
274 <code class="varname">ctx</code>
275 to convert the contents of packet
276 <code class="varname">pkt</code>
277 to a
278 <span class="type">lwres_gnbarequest_t</span>
279 structure.
280 Buffer
281 <code class="varname">b</code>
282 provides space to be used for storing this structure.
283 When the function succeeds, the resulting
284 <span class="type">lwres_gnbarequest_t</span>
285 is made available through
286 <code class="varname">*structp</code>.
287 <code class="function">lwres_gnbaresponse_parse()</code>
288 offers the same semantics as
289 <code class="function">lwres_gnbarequest_parse()</code>
290 except it yields a
291 <span class="type">lwres_gnbaresponse_t</span>
292 structure.
293 </p>
294 <p>
295 <code class="function">lwres_gnbaresponse_free()</code>
296 and
297 <code class="function">lwres_gnbarequest_free()</code>
298 release the memory in resolver context
299 <code class="varname">ctx</code>
300 that was allocated to the
301 <span class="type">lwres_gnbaresponse_t</span>
302 or
303 <span class="type">lwres_gnbarequest_t</span>
304 structures referenced via
305 <code class="varname">structp</code>.
306 Any memory associated with ancillary buffers and strings for those
307 structures is also discarded.
308 </p>
309 </div>
310 <div class="refsect1" lang="en">
311 <a name="id2549733"></a><h2>RETURN VALUES</h2>
312 <p>
313 The getnamebyaddr opcode functions
314 <code class="function">lwres_gnbarequest_render()</code>,
315 <code class="function">lwres_gnbaresponse_render()</code>
316 <code class="function">lwres_gnbarequest_parse()</code>
317 and
318 <code class="function">lwres_gnbaresponse_parse()</code>
319 all return
320 <span class="errorcode">LWRES_R_SUCCESS</span>
321 on success.
322 They return
323 <span class="errorcode">LWRES_R_NOMEMORY</span>
324 if memory allocation fails.
325 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
326 is returned if the available space in the buffer
327 <code class="varname">b</code>
328 is too small to accommodate the packet header or the
329 <span class="type">lwres_gnbarequest_t</span>
330 and
331 <span class="type">lwres_gnbaresponse_t</span>
332 structures.
333 <code class="function">lwres_gnbarequest_parse()</code>
334 and
335 <code class="function">lwres_gnbaresponse_parse()</code>
336 will return
337 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
338 if the buffer is not empty after decoding the received packet.
339 These functions will return
340 <span class="errorcode">LWRES_R_FAILURE</span>
341 if
342 <em class="structfield"><code>pktflags</code></em>
343 in the packet header structure
344 <span class="type">lwres_lwpacket_t</span>
345 indicate that the packet is not a response to an earlier query.
346 </p>
347 </div>
348 <div class="refsect1" lang="en">
349 <a name="id2549866"></a><h2>SEE ALSO</h2>
350 <p>
351 <span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>.
352 </p>
353 </div>
354 </div></body>
355 </html>