Merge from vendor branch HEIMDAL:
[dragonfly.git] / contrib / bind-9.2.4rc7 / lib / lwres / man / lwres_resutil.html
1 <!--
2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
3  - Copyright (C) 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
18 <!-- $Id: lwres_resutil.html,v 1.8.2.2 2004/03/15 04:45:05 marka Exp $ -->
19
20 <HTML
21 ><HEAD
22 ><TITLE
23 >lwres_resutil</TITLE
24 ><META
25 NAME="GENERATOR"
26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
27 "></HEAD
28 ><BODY
29 CLASS="REFENTRY"
30 BGCOLOR="#FFFFFF"
31 TEXT="#000000"
32 LINK="#0000FF"
33 VLINK="#840084"
34 ALINK="#0000FF"
35 ><H1
36 ><A
37 NAME="AEN1"
38 >lwres_resutil</A
39 ></H1
40 ><DIV
41 CLASS="REFNAMEDIV"
42 ><A
43 NAME="AEN8"
44 ></A
45 ><H2
46 >Name</H2
47 >lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr&nbsp;--&nbsp;lightweight resolver utility functions</DIV
48 ><DIV
49 CLASS="REFSYNOPSISDIV"
50 ><A
51 NAME="AEN14"
52 ></A
53 ><H2
54 >Synopsis</H2
55 ><DIV
56 CLASS="FUNCSYNOPSIS"
57 ><A
58 NAME="AEN15"
59 ></A
60 ><P
61 ></P
62 ><PRE
63 CLASS="FUNCSYNOPSISINFO"
64 >#include &lt;lwres/lwres.h&gt;</PRE
65 ><P
66 ><CODE
67 ><CODE
68 CLASS="FUNCDEF"
69 >lwres_result_t
70 lwres_string_parse</CODE
71 >(lwres_buffer_t *b, char **c, lwres_uint16_t *len);</CODE
72 ></P
73 ><P
74 ><CODE
75 ><CODE
76 CLASS="FUNCDEF"
77 >lwres_result_t
78 lwres_addr_parse</CODE
79 >(lwres_buffer_t *b, lwres_addr_t *addr);</CODE
80 ></P
81 ><P
82 ><CODE
83 ><CODE
84 CLASS="FUNCDEF"
85 >lwres_result_t
86 lwres_getaddrsbyname</CODE
87 >(lwres_context_t *ctx, const char *name, lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);</CODE
88 ></P
89 ><P
90 ><CODE
91 ><CODE
92 CLASS="FUNCDEF"
93 >lwres_result_t
94 lwres_getnamebyaddr</CODE
95 >(lwres_context_t *ctx, lwres_uint32_t addrtype, lwres_uint16_t addrlen, const unsigned char *addr, lwres_gnbaresponse_t **structp);</CODE
96 ></P
97 ><P
98 ></P
99 ></DIV
100 ></DIV
101 ><DIV
102 CLASS="REFSECT1"
103 ><A
104 NAME="AEN43"
105 ></A
106 ><H2
107 >DESCRIPTION</H2
108 ><P
109 ><TT
110 CLASS="FUNCTION"
111 >lwres_string_parse()</TT
112 > retrieves a DNS-encoded
113 string starting the current pointer of lightweight resolver buffer
114 <TT
115 CLASS="PARAMETER"
116 ><I
117 >b</I
118 ></TT
119 >: i.e.  <TT
120 CLASS="CONSTANT"
121 >b-&gt;current</TT
122 >.
123 When the function returns, the address of the first byte of the
124 encoded string is returned via <TT
125 CLASS="PARAMETER"
126 ><I
127 >*c</I
128 ></TT
129 > and the
130 length of that string is given by <TT
131 CLASS="PARAMETER"
132 ><I
133 >*len</I
134 ></TT
135 >.  The
136 buffer's current pointer is advanced to point at the character
137 following the string length, the encoded string, and the trailing
138 <SPAN
139 CLASS="TYPE"
140 >NULL</SPAN
141 > character.</P
142 ><P
143 ><TT
144 CLASS="FUNCTION"
145 >lwres_addr_parse()</TT
146 > extracts an address from the
147 buffer <TT
148 CLASS="PARAMETER"
149 ><I
150 >b</I
151 ></TT
152 >.  The buffer's current pointer
153 <TT
154 CLASS="CONSTANT"
155 >b-&gt;current</TT
156 > is presumed to point at an encoded
157 address: the address preceded by a 32-bit protocol family identifier
158 and a 16-bit length field.  The encoded address is copied to
159 <TT
160 CLASS="CONSTANT"
161 >addr-&gt;address</TT
162 > and
163 <TT
164 CLASS="CONSTANT"
165 >addr-&gt;length</TT
166 > indicates the size in bytes of
167 the address that was copied.  <TT
168 CLASS="CONSTANT"
169 >b-&gt;current</TT
170 > is
171 advanced to point at the next byte of available data in the buffer
172 following the encoded address.</P
173 ><P
174 ><TT
175 CLASS="FUNCTION"
176 >lwres_getaddrsbyname()</TT
177 >
178 and
179 <TT
180 CLASS="FUNCTION"
181 >lwres_getnamebyaddr()</TT
182 >
183 use the
184 <SPAN
185 CLASS="TYPE"
186 >lwres_gnbaresponse_t</SPAN
187 >
188 structure defined below:
189 <PRE
190 CLASS="PROGRAMLISTING"
191 >typedef struct {
192         lwres_uint32_t          flags;
193         lwres_uint16_t          naliases;
194         lwres_uint16_t          naddrs;
195         char                   *realname;
196         char                  **aliases;
197         lwres_uint16_t          realnamelen;
198         lwres_uint16_t         *aliaslen;
199         lwres_addrlist_t        addrs;
200         void                   *base;
201         size_t                  baselen;
202 } lwres_gabnresponse_t;</PRE
203 >
204 The contents of this structure are not manipulated directly but
205 they are controlled through the
206 <SPAN
207 CLASS="CITEREFENTRY"
208 ><SPAN
209 CLASS="REFENTRYTITLE"
210 >lwres_gabn</SPAN
211 >(3)</SPAN
212 >
213 functions.</P
214 ><P
215 >The lightweight resolver uses
216 <TT
217 CLASS="FUNCTION"
218 >lwres_getaddrsbyname()</TT
219 > to perform foward lookups.
220 Hostname <TT
221 CLASS="PARAMETER"
222 ><I
223 >name</I
224 ></TT
225 > is looked up using the resolver
226 context <TT
227 CLASS="PARAMETER"
228 ><I
229 >ctx</I
230 ></TT
231 > for memory allocation.
232 <TT
233 CLASS="PARAMETER"
234 ><I
235 >addrtypes</I
236 ></TT
237 > is a bitmask indicating which type of
238 addresses are to be looked up.  Current values for this bitmask are
239 <SPAN
240 CLASS="TYPE"
241 >LWRES_ADDRTYPE_V4</SPAN
242 > for IPv4 addresses and
243 <SPAN
244 CLASS="TYPE"
245 >LWRES_ADDRTYPE_V6</SPAN
246 > for IPv6 addresses.  Results of the
247 lookup are returned in <TT
248 CLASS="PARAMETER"
249 ><I
250 >*structp</I
251 ></TT
252 >.</P
253 ><P
254 ><TT
255 CLASS="FUNCTION"
256 >lwres_getnamebyaddr()</TT
257 > performs reverse lookups.
258 Resolver context <TT
259 CLASS="PARAMETER"
260 ><I
261 >ctx</I
262 ></TT
263 > is used for memory
264 allocation.  The address type is indicated by
265 <TT
266 CLASS="PARAMETER"
267 ><I
268 >addrtype</I
269 ></TT
270 >: <SPAN
271 CLASS="TYPE"
272 >LWRES_ADDRTYPE_V4</SPAN
273 > or
274 <SPAN
275 CLASS="TYPE"
276 >LWRES_ADDRTYPE_V6</SPAN
277 >.  The address to be looked up is given
278 by <TT
279 CLASS="PARAMETER"
280 ><I
281 >addr</I
282 ></TT
283 > and its length is
284 <TT
285 CLASS="PARAMETER"
286 ><I
287 >addrlen</I
288 ></TT
289 > bytes.  The result of the function call
290 is made available through <TT
291 CLASS="PARAMETER"
292 ><I
293 >*structp</I
294 ></TT
295 >.</P
296 ></DIV
297 ><DIV
298 CLASS="REFSECT1"
299 ><A
300 NAME="AEN84"
301 ></A
302 ><H2
303 >RETURN VALUES</H2
304 ><P
305 >Successful calls to
306 <TT
307 CLASS="FUNCTION"
308 >lwres_string_parse()</TT
309 >
310 and
311 <TT
312 CLASS="FUNCTION"
313 >lwres_addr_parse()</TT
314 >
315 return
316 <SPAN
317 CLASS="ERRORCODE"
318 >LWRES_R_SUCCESS.</SPAN
319 >
320 Both functions return
321 <SPAN
322 CLASS="ERRORCODE"
323 >LWRES_R_FAILURE</SPAN
324 >
325 if the buffer is corrupt or
326 <SPAN
327 CLASS="ERRORCODE"
328 >LWRES_R_UNEXPECTEDEND</SPAN
329 >
330 if the buffer has less space than expected for the components of the
331 encoded string or address.</P
332 ><P
333 ><TT
334 CLASS="FUNCTION"
335 >lwres_getaddrsbyname()</TT
336 >
337 returns
338 <SPAN
339 CLASS="ERRORCODE"
340 >LWRES_R_SUCCESS</SPAN
341 >
342 on success and it returns
343 <SPAN
344 CLASS="ERRORCODE"
345 >LWRES_R_NOTFOUND</SPAN
346 >
347 if the hostname
348 <TT
349 CLASS="PARAMETER"
350 ><I
351 >name</I
352 ></TT
353 >
354 could not be found.</P
355 ><P
356 ><SPAN
357 CLASS="ERRORCODE"
358 >LWRES_R_SUCCESS</SPAN
359 >
360 is returned by a successful call to
361 <TT
362 CLASS="FUNCTION"
363 >lwres_getnamebyaddr()</TT
364 >.</P
365 ><P
366 >Both
367 <TT
368 CLASS="FUNCTION"
369 >lwres_getaddrsbyname()</TT
370 >
371 and
372 <TT
373 CLASS="FUNCTION"
374 >lwres_getnamebyaddr()</TT
375 >
376 return
377 <SPAN
378 CLASS="ERRORCODE"
379 >LWRES_R_NOMEMORY</SPAN
380 >
381 when memory allocation requests fail and
382 <SPAN
383 CLASS="ERRORCODE"
384 >LWRES_R_UNEXPECTEDEND</SPAN
385 >
386 if the buffers used for sending queries and receiving replies are too
387 small.</P
388 ></DIV
389 ><DIV
390 CLASS="REFSECT1"
391 ><A
392 NAME="AEN105"
393 ></A
394 ><H2
395 >SEE ALSO</H2
396 ><P
397 ><SPAN
398 CLASS="CITEREFENTRY"
399 ><SPAN
400 CLASS="REFENTRYTITLE"
401 >lwres_buffer</SPAN
402 >(3)</SPAN
403 >,
404
405 <SPAN
406 CLASS="CITEREFENTRY"
407 ><SPAN
408 CLASS="REFENTRYTITLE"
409 >lwres_gabn</SPAN
410 >(3)</SPAN
411 >.</P
412 ></DIV
413 ></BODY
414 ></HTML
415 >