Merge from vendor branch WPA_SUPPLICANT:
[dragonfly.git] / contrib / bind-9.2.4rc7 / lib / lwres / man / lwres_context.html
1 <!--
2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
3  - Copyright (C) 2001, 2003  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_context.html,v 1.5.2.3 2004/03/15 04:45:01 marka Exp $ -->
19
20 <HTML
21 ><HEAD
22 ><TITLE
23 >lwres_context</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_context</A
39 ></H1
40 ><DIV
41 CLASS="REFNAMEDIV"
42 ><A
43 NAME="AEN8"
44 ></A
45 ><H2
46 >Name</H2
47 >lwres_context_create, lwres_context_destroy, lwres_context_nextserial, lwres_context_initserial, lwres_context_freemem, lwres_context_allocmem, lwres_context_sendrecv&nbsp;--&nbsp;lightweight resolver context management</DIV
48 ><DIV
49 CLASS="REFSYNOPSISDIV"
50 ><A
51 NAME="AEN17"
52 ></A
53 ><H2
54 >Synopsis</H2
55 ><DIV
56 CLASS="FUNCSYNOPSIS"
57 ><A
58 NAME="AEN18"
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_context_create</CODE
71 >(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, lwres_free_t free_function);</CODE
72 ></P
73 ><P
74 ><CODE
75 ><CODE
76 CLASS="FUNCDEF"
77 >lwres_result_t
78 lwres_context_destroy</CODE
79 >(lwres_context_t **contextp);</CODE
80 ></P
81 ><P
82 ><CODE
83 ><CODE
84 CLASS="FUNCDEF"
85 >void
86 lwres_context_initserial</CODE
87 >(lwres_context_t *ctx, lwres_uint32_t serial);</CODE
88 ></P
89 ><P
90 ><CODE
91 ><CODE
92 CLASS="FUNCDEF"
93 >lwres_uint32_t
94 lwres_context_nextserial</CODE
95 >(lwres_context_t *ctx);</CODE
96 ></P
97 ><P
98 ><CODE
99 ><CODE
100 CLASS="FUNCDEF"
101 >void
102 lwres_context_freemem</CODE
103 >(lwres_context_t *ctx, void *mem, size_t len);</CODE
104 ></P
105 ><P
106 ><CODE
107 ><CODE
108 CLASS="FUNCDEF"
109 >void
110 lwres_context_allocmem</CODE
111 >(lwres_context_t *ctx, size_t len);</CODE
112 ></P
113 ><P
114 ><CODE
115 ><CODE
116 CLASS="FUNCDEF"
117 >void *
118 lwres_context_sendrecv</CODE
119 >(lwres_context_t *ctx, void *sendbase, int sendlen, void *recvbase, int recvlen, int *recvd_len);</CODE
120 ></P
121 ><P
122 ></P
123 ></DIV
124 ></DIV
125 ><DIV
126 CLASS="REFSECT1"
127 ><A
128 NAME="AEN60"
129 ></A
130 ><H2
131 >DESCRIPTION</H2
132 ><P
133 ><TT
134 CLASS="FUNCTION"
135 >lwres_context_create()</TT
136 >
137 creates a
138 <SPAN
139 CLASS="TYPE"
140 >lwres_context_t</SPAN
141 >
142 structure for use in lightweight resolver operations.
143 It holds a socket and other data needed for communicating
144 with a resolver daemon.
145 The new
146 <SPAN
147 CLASS="TYPE"
148 >lwres_context_t</SPAN
149 >
150 is returned through
151 <TT
152 CLASS="PARAMETER"
153 ><I
154 >contextp</I
155 ></TT
156 >,
157
158 a pointer to a
159 <SPAN
160 CLASS="TYPE"
161 >lwres_context_t</SPAN
162 >
163 pointer.  This 
164 <SPAN
165 CLASS="TYPE"
166 >lwres_context_t</SPAN
167 >
168 pointer must initially be NULL, and is modified 
169 to point to the newly created
170 <SPAN
171 CLASS="TYPE"
172 >lwres_context_t</SPAN
173 >.&#13;</P
174 ><P
175 >When the lightweight resolver needs to perform dynamic memory
176 allocation, it will call
177 <TT
178 CLASS="PARAMETER"
179 ><I
180 >malloc_function</I
181 ></TT
182 >
183 to allocate memory and
184 <TT
185 CLASS="PARAMETER"
186 ><I
187 >free_function</I
188 ></TT
189 >
190
191 to free it.  If 
192 <TT
193 CLASS="PARAMETER"
194 ><I
195 >malloc_function</I
196 ></TT
197 >
198 and
199 <TT
200 CLASS="PARAMETER"
201 ><I
202 >free_function</I
203 ></TT
204 >
205
206 are NULL, memory is allocated using
207 .Xr malloc 3
208 and
209 <SPAN
210 CLASS="CITEREFENTRY"
211 ><SPAN
212 CLASS="REFENTRYTITLE"
213 >free</SPAN
214 >(3)</SPAN
215 >.
216
217 It is not permitted to have a NULL
218 <TT
219 CLASS="PARAMETER"
220 ><I
221 >malloc_function</I
222 ></TT
223 >
224 and a non-NULL
225 <TT
226 CLASS="PARAMETER"
227 ><I
228 >free_function</I
229 ></TT
230 >
231 or vice versa.
232 <TT
233 CLASS="PARAMETER"
234 ><I
235 >arg</I
236 ></TT
237 >
238 is passed as the first parameter to the memory
239 allocation functions.  
240 If
241 <TT
242 CLASS="PARAMETER"
243 ><I
244 >malloc_function</I
245 ></TT
246 >
247 and
248 <TT
249 CLASS="PARAMETER"
250 ><I
251 >free_function</I
252 ></TT
253 >
254 are NULL,
255 <TT
256 CLASS="PARAMETER"
257 ><I
258 >arg</I
259 ></TT
260 >
261
262 is unused and should be passed as NULL.</P
263 ><P
264 >Once memory for the structure has been allocated,
265 it is initialized using
266 <SPAN
267 CLASS="CITEREFENTRY"
268 ><SPAN
269 CLASS="REFENTRYTITLE"
270 >lwres_conf_init</SPAN
271 >(3)</SPAN
272 >
273
274 and returned via
275 <TT
276 CLASS="PARAMETER"
277 ><I
278 >*contextp</I
279 ></TT
280 >.&#13;</P
281 ><P
282 ><TT
283 CLASS="FUNCTION"
284 >lwres_context_destroy()</TT
285 >
286 destroys a 
287 <SPAN
288 CLASS="TYPE"
289 >lwres_context_t</SPAN
290 >,
291
292 closing its socket.
293 <TT
294 CLASS="PARAMETER"
295 ><I
296 >contextp</I
297 ></TT
298 >
299 is a pointer to a pointer to the context that is to be destroyed.
300 The pointer will be set to NULL when the context has been destroyed.</P
301 ><P
302 >The context holds a serial number that is used to identify resolver
303 request packets and associate responses with the corresponding requests.
304 This serial number is controlled using
305 <TT
306 CLASS="FUNCTION"
307 >lwres_context_initserial()</TT
308 >
309 and
310 <TT
311 CLASS="FUNCTION"
312 >lwres_context_nextserial()</TT
313 >.
314 <TT
315 CLASS="FUNCTION"
316 >lwres_context_initserial()</TT
317 >
318 sets the serial number for context
319 <TT
320 CLASS="PARAMETER"
321 ><I
322 >*ctx</I
323 ></TT
324 >
325 to
326 <TT
327 CLASS="PARAMETER"
328 ><I
329 >serial</I
330 ></TT
331 >.
332
333 <TT
334 CLASS="FUNCTION"
335 >lwres_context_nextserial()</TT
336 >
337 increments the serial number and returns the previous value.</P
338 ><P
339 >Memory for a lightweight resolver context is allocated and freed using
340 <TT
341 CLASS="FUNCTION"
342 >lwres_context_allocmem()</TT
343 >
344 and
345 <TT
346 CLASS="FUNCTION"
347 >lwres_context_freemem()</TT
348 >.
349 These use whatever allocations were defined when the context was
350 created with
351 <TT
352 CLASS="FUNCTION"
353 >lwres_context_create()</TT
354 >.
355 <TT
356 CLASS="FUNCTION"
357 >lwres_context_allocmem()</TT
358 >
359 allocates
360 <TT
361 CLASS="PARAMETER"
362 ><I
363 >len</I
364 ></TT
365 >
366 bytes of memory and if successful returns a pointer to the allocated
367 storage.
368 <TT
369 CLASS="FUNCTION"
370 >lwres_context_freemem()</TT
371 >
372 frees
373 <TT
374 CLASS="PARAMETER"
375 ><I
376 >len</I
377 ></TT
378 >
379 bytes of space starting at location
380 <TT
381 CLASS="PARAMETER"
382 ><I
383 >mem</I
384 ></TT
385 >.&#13;</P
386 ><P
387 ><TT
388 CLASS="FUNCTION"
389 >lwres_context_sendrecv()</TT
390 >
391 performs I/O for the context
392 <TT
393 CLASS="PARAMETER"
394 ><I
395 >ctx</I
396 ></TT
397 >.
398
399 Data are read and written from the context's socket.
400 It writes data from
401 <TT
402 CLASS="PARAMETER"
403 ><I
404 >sendbase</I
405 ></TT
406 >
407 &mdash; typically a lightweight resolver query packet &mdash;
408 and waits for a reply which is copied to the receive buffer at
409 <TT
410 CLASS="PARAMETER"
411 ><I
412 >recvbase</I
413 ></TT
414 >.
415
416 The number of bytes that were written to this receive buffer is
417 returned in
418 <TT
419 CLASS="PARAMETER"
420 ><I
421 >*recvd_len</I
422 ></TT
423 >.&#13;</P
424 ></DIV
425 ><DIV
426 CLASS="REFSECT1"
427 ><A
428 NAME="AEN115"
429 ></A
430 ><H2
431 >RETURN VALUES</H2
432 ><P
433 ><TT
434 CLASS="FUNCTION"
435 >lwres_context_create()</TT
436 >
437 returns
438 <SPAN
439 CLASS="ERRORCODE"
440 >LWRES_R_NOMEMORY</SPAN
441 >
442 if memory for the
443 <SPAN
444 CLASS="TYPE"
445 >struct lwres_context</SPAN
446 >
447 could not be allocated, 
448 <SPAN
449 CLASS="ERRORCODE"
450 >LWRES_R_SUCCESS</SPAN
451 >
452 otherwise.</P
453 ><P
454 >Successful calls to the memory allocator
455 <TT
456 CLASS="FUNCTION"
457 >lwres_context_allocmem()</TT
458 >
459 return a pointer to the start of the allocated space.
460 It returns NULL if memory could not be allocated.</P
461 ><P
462 ><SPAN
463 CLASS="ERRORCODE"
464 >LWRES_R_SUCCESS</SPAN
465 >
466 is returned when
467 <TT
468 CLASS="FUNCTION"
469 >lwres_context_sendrecv()</TT
470 >
471 completes successfully.
472 <SPAN
473 CLASS="ERRORCODE"
474 >LWRES_R_IOERROR</SPAN
475 >
476 is returned if an I/O error occurs and
477 <SPAN
478 CLASS="ERRORCODE"
479 >LWRES_R_TIMEOUT</SPAN
480 >
481 is returned if
482 <TT
483 CLASS="FUNCTION"
484 >lwres_context_sendrecv()</TT
485 >
486 times out waiting for a response.</P
487 ></DIV
488 ><DIV
489 CLASS="REFSECT1"
490 ><A
491 NAME="AEN130"
492 ></A
493 ><H2
494 >SEE ALSO</H2
495 ><P
496 ><SPAN
497 CLASS="CITEREFENTRY"
498 ><SPAN
499 CLASS="REFENTRYTITLE"
500 >lwres_conf_init</SPAN
501 >(3)</SPAN
502 >,
503
504 <SPAN
505 CLASS="CITEREFENTRY"
506 ><SPAN
507 CLASS="REFENTRYTITLE"
508 >malloc</SPAN
509 >(3)</SPAN
510 >,
511
512 <SPAN
513 CLASS="CITEREFENTRY"
514 ><SPAN
515 CLASS="REFENTRYTITLE"
516 >free</SPAN
517 >(3)</SPAN
518 >.</P
519 ></DIV
520 ></BODY
521 ></HTML
522 >