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