| blob | bf422f64462dfb5955e78f35f41537fb339d8416 |
1 .TH "event2/dns_compat.h" 3 "Tue Jan 27 2015" "libevent" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 event2/dns_compat.h \-
6 .PP
7 Potentially non-threadsafe versions of the functions in \fBdns\&.h\fP: provided only for backwards compatibility\&.
9 .SH SYNOPSIS
10 .br
11 .PP
12 \fC#include <event2/event-config\&.h>\fP
13 .br
14 \fC#include <event2/util\&.h>\fP
15 .br
17 .SS "Functions"
19 .in +1c
20 .ti -1c
21 .RI "struct evdns_server_port * \fBevdns_add_server_port\fP (\fBevutil_socket_t\fP socket, int flags, \fBevdns_request_callback_fn_type\fP callback, void *user_data)"
22 .br
23 .RI "\fIAs evdns_server_new_with_base\&. \fP"
24 .ti -1c
25 .RI "int \fBevdns_clear_nameservers_and_suspend\fP (void)"
26 .br
27 .RI "\fIRemove all configured nameservers, and suspend all pending resolves\&. \fP"
28 .ti -1c
29 .RI "int \fBevdns_count_nameservers\fP (void)"
30 .br
31 .RI "\fIGet the number of configured nameservers\&. \fP"
32 .ti -1c
33 .RI "struct evdns_base * \fBevdns_get_global_base\fP (void)"
34 .br
35 .RI "\fIReturn the global evdns_base created by \fBevent_init()\fP and used by the other deprecated functions\&. \fP"
36 .ti -1c
37 .RI "int \fBevdns_init\fP (void)"
38 .br
39 .RI "\fIInitialize the asynchronous DNS library\&. \fP"
40 .ti -1c
41 .RI "int \fBevdns_nameserver_add\fP (unsigned long int address)"
42 .br
43 .RI "\fIAdd a nameserver\&. \fP"
44 .ti -1c
45 .RI "int \fBevdns_nameserver_ip_add\fP (const char *ip_as_string)"
46 .br
47 .RI "\fIAdd a nameserver\&. \fP"
48 .ti -1c
49 .RI "int \fBevdns_resolv_conf_parse\fP (int flags, const char *const filename)"
50 .br
51 .RI "\fIParse a resolv\&.conf file\&. \fP"
52 .ti -1c
53 .RI "int \fBevdns_resolve_ipv4\fP (const char *name, int flags, \fBevdns_callback_type\fP callback, void *ptr)"
54 .br
55 .RI "\fILookup an A record for a given name\&. \fP"
56 .ti -1c
57 .RI "int \fBevdns_resolve_ipv6\fP (const char *name, int flags, \fBevdns_callback_type\fP callback, void *ptr)"
58 .br
59 .RI "\fILookup an AAAA record for a given name\&. \fP"
60 .ti -1c
61 .RI "int \fBevdns_resolve_reverse\fP (const struct in_addr *in, int flags, \fBevdns_callback_type\fP callback, void *ptr)"
62 .br
63 .RI "\fILookup a PTR record for a given IP address\&. \fP"
64 .ti -1c
65 .RI "int \fBevdns_resolve_reverse_ipv6\fP (const struct in6_addr *in, int flags, \fBevdns_callback_type\fP callback, void *ptr)"
66 .br
67 .RI "\fILookup a PTR record for a given IPv6 address\&. \fP"
68 .ti -1c
69 .RI "int \fBevdns_resume\fP (void)"
70 .br
71 .RI "\fIResume normal operation and continue any suspended resolve requests\&. \fP"
72 .ti -1c
73 .RI "void \fBevdns_search_add\fP (const char *domain)"
74 .br
75 .RI "\fIAdd a domain to the list of search domains\&. \fP"
76 .ti -1c
77 .RI "void \fBevdns_search_clear\fP (void)"
78 .br
79 .RI "\fIClear the list of search domains\&. \fP"
80 .ti -1c
81 .RI "void \fBevdns_search_ndots_set\fP (const int ndots)"
82 .br
83 .RI "\fISet the 'ndots' parameter for searches\&. \fP"
84 .ti -1c
85 .RI "int \fBevdns_set_option\fP (const char *option, const char *val, int flags)"
86 .br
87 .RI "\fISet the value of a configuration option\&. \fP"
88 .ti -1c
89 .RI "void \fBevdns_shutdown\fP (int fail_requests)"
90 .br
91 .RI "\fIShut down the asynchronous DNS resolver and terminate all active requests\&. \fP"
92 .in -1c
93 .SH "Detailed Description"
94 .PP
95 Potentially non-threadsafe versions of the functions in \fBdns\&.h\fP: provided only for backwards compatibility\&.
98 .SH "Function Documentation"
99 .PP
100 .SS "struct evdns_server_port* evdns_add_server_port (\fBevutil_socket_t\fPsocket, intflags, \fBevdns_request_callback_fn_type\fPcallback, void *user_data)"
102 .PP
103 As evdns_server_new_with_base\&.
104 .PP
105 \fBDeprecated\fP
106 .RS 4
107 This function is deprecated because it does not allow the caller to specify which even_base it uses\&. The recommended function is \fBevdns_add_server_port_with_base()\fP\&.
108 .RE
109 .PP
111 .SS "int evdns_clear_nameservers_and_suspend (void)"
113 .PP
114 Remove all configured nameservers, and suspend all pending resolves\&. Resolves will not necessarily be re-attempted until \fBevdns_resume()\fP is called\&.
115 .PP
116 \fBDeprecated\fP
117 .RS 4
118 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_clear_nameservers_and_suspend()\fP\&.
119 .RE
120 .PP
121 .PP
122 \fBReturns:\fP
123 .RS 4
124 0 if successful, or -1 if an error occurred
125 .RE
126 .PP
127 \fBSee also:\fP
128 .RS 4
129 \fBevdns_resume()\fP
130 .RE
131 .PP
133 .SS "int evdns_count_nameservers (void)"
135 .PP
136 Get the number of configured nameservers\&. This returns the number of configured nameservers (not necessarily the number of running nameservers)\&. This is useful for double-checking whether our calls to the various nameserver configuration functions have been successful\&.
137 .PP
138 \fBDeprecated\fP
139 .RS 4
140 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_count_nameservers()\fP\&.
141 .RE
142 .PP
143 .PP
144 \fBReturns:\fP
145 .RS 4
146 the number of configured nameservers
147 .RE
148 .PP
149 \fBSee also:\fP
150 .RS 4
151 \fBevdns_nameserver_add()\fP
152 .RE
153 .PP
155 .SS "struct evdns_base* evdns_get_global_base (void)"
157 .PP
158 Return the global evdns_base created by \fBevent_init()\fP and used by the other deprecated functions\&.
159 .PP
160 \fBDeprecated\fP
161 .RS 4
162 This function is deprecated because use of the global evdns_base is error-prone\&.
163 .RE
164 .PP
166 .SS "int evdns_init (void)"
168 .PP
169 Initialize the asynchronous DNS library\&. This function initializes support for non-blocking name resolution by calling \fBevdns_resolv_conf_parse()\fP on UNIX and evdns_config_windows_nameservers() on Windows\&.
170 .PP
171 \fBDeprecated\fP
172 .RS 4
173 This function is deprecated because it always uses the current event base, and is easily confused by multiple calls to \fBevent_init()\fP, and so is not safe for multithreaded use\&. Additionally, it allocates a global structure that only one thread can use\&. The replacement is \fBevdns_base_new()\fP\&.
174 .RE
175 .PP
176 .PP
177 \fBReturns:\fP
178 .RS 4
179 0 if successful, or -1 if an error occurred
180 .RE
181 .PP
182 \fBSee also:\fP
183 .RS 4
184 \fBevdns_shutdown()\fP
185 .RE
186 .PP
188 .SS "int evdns_nameserver_add (unsigned long intaddress)"
190 .PP
191 Add a nameserver\&. The address should be an IPv4 address in network byte order\&. The type of address is chosen so that it matches in_addr\&.s_addr\&.
192 .PP
193 \fBDeprecated\fP
194 .RS 4
195 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_nameserver_add()\fP\&.
196 .RE
197 .PP
198 .PP
199 \fBParameters:\fP
200 .RS 4
201 \fIaddress\fP an IP address in network byte order
202 .RE
203 .PP
204 \fBReturns:\fP
205 .RS 4
206 0 if successful, or -1 if an error occurred
207 .RE
208 .PP
209 \fBSee also:\fP
210 .RS 4
211 \fBevdns_nameserver_ip_add()\fP
212 .RE
213 .PP
215 .SS "int evdns_nameserver_ip_add (const char *ip_as_string)"
217 .PP
218 Add a nameserver\&. This wraps the \fBevdns_nameserver_add()\fP function by parsing a string as an IP address and adds it as a nameserver\&.
219 .PP
220 \fBDeprecated\fP
221 .RS 4
222 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_nameserver_ip_add()\fP\&.
223 .RE
224 .PP
225 .PP
226 \fBReturns:\fP
227 .RS 4
228 0 if successful, or -1 if an error occurred
229 .RE
230 .PP
231 \fBSee also:\fP
232 .RS 4
233 \fBevdns_nameserver_add()\fP
234 .RE
235 .PP
237 .SS "int evdns_resolv_conf_parse (intflags, const char *constfilename)"
239 .PP
240 Parse a resolv\&.conf file\&. The 'flags' parameter determines what information is parsed from the resolv\&.conf file\&. See the man page for resolv\&.conf for the format of this file\&.
241 .PP
242 The following directives are not parsed from the file: sortlist, rotate, no-check-names, inet6, debug\&.
243 .PP
244 If this function encounters an error, the possible return values are: 1 = failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of memory, 5 = short read from file, 6 = no nameservers listed in the file
245 .PP
246 \fBDeprecated\fP
247 .RS 4
248 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolv_conf_parse()\fP\&.
249 .RE
250 .PP
251 .PP
252 \fBParameters:\fP
253 .RS 4
254 \fIflags\fP any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC| DNS_OPTIONS_ALL
255 .br
256 \fIfilename\fP the path to the resolv\&.conf file
257 .RE
258 .PP
259 \fBReturns:\fP
260 .RS 4
261 0 if successful, or various positive error codes if an error occurred (see above)
262 .RE
263 .PP
264 \fBSee also:\fP
265 .RS 4
266 resolv\&.conf(3), evdns_config_windows_nameservers()
267 .RE
268 .PP
270 .SS "int evdns_resolve_ipv4 (const char *name, intflags, \fBevdns_callback_type\fPcallback, void *ptr)"
272 .PP
273 Lookup an A record for a given name\&.
274 .PP
275 \fBDeprecated\fP
276 .RS 4
277 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolve_ipv4()\fP\&.
278 .RE
279 .PP
280 .PP
281 \fBParameters:\fP
282 .RS 4
283 \fIname\fP a DNS hostname
284 .br
285 \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&.
286 .br
287 \fIcallback\fP a callback function to invoke when the request is completed
288 .br
289 \fIptr\fP an argument to pass to the callback function
290 .RE
291 .PP
292 \fBReturns:\fP
293 .RS 4
294 0 if successful, or -1 if an error occurred
295 .RE
296 .PP
297 \fBSee also:\fP
298 .RS 4
299 \fBevdns_resolve_ipv6()\fP, \fBevdns_resolve_reverse()\fP, \fBevdns_resolve_reverse_ipv6()\fP
300 .RE
301 .PP
303 .SS "int evdns_resolve_ipv6 (const char *name, intflags, \fBevdns_callback_type\fPcallback, void *ptr)"
305 .PP
306 Lookup an AAAA record for a given name\&.
307 .PP
308 \fBParameters:\fP
309 .RS 4
310 \fIname\fP a DNS hostname
311 .br
312 \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&.
313 .br
314 \fIcallback\fP a callback function to invoke when the request is completed
315 .br
316 \fIptr\fP an argument to pass to the callback function
317 .RE
318 .PP
319 \fBReturns:\fP
320 .RS 4
321 0 if successful, or -1 if an error occurred
322 .RE
323 .PP
324 \fBSee also:\fP
325 .RS 4
326 \fBevdns_resolve_ipv4()\fP, \fBevdns_resolve_reverse()\fP, \fBevdns_resolve_reverse_ipv6()\fP
327 .RE
328 .PP
330 .SS "int evdns_resolve_reverse (const struct in_addr *in, intflags, \fBevdns_callback_type\fPcallback, void *ptr)"
332 .PP
333 Lookup a PTR record for a given IP address\&.
334 .PP
335 \fBDeprecated\fP
336 .RS 4
337 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolve_reverse()\fP\&.
338 .RE
339 .PP
340 .PP
341 \fBParameters:\fP
342 .RS 4
343 \fIin\fP an IPv4 address
344 .br
345 \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&.
346 .br
347 \fIcallback\fP a callback function to invoke when the request is completed
348 .br
349 \fIptr\fP an argument to pass to the callback function
350 .RE
351 .PP
352 \fBReturns:\fP
353 .RS 4
354 0 if successful, or -1 if an error occurred
355 .RE
356 .PP
357 \fBSee also:\fP
358 .RS 4
359 \fBevdns_resolve_reverse_ipv6()\fP
360 .RE
361 .PP
363 .SS "int evdns_resolve_reverse_ipv6 (const struct in6_addr *in, intflags, \fBevdns_callback_type\fPcallback, void *ptr)"
365 .PP
366 Lookup a PTR record for a given IPv6 address\&.
367 .PP
368 \fBDeprecated\fP
369 .RS 4
370 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolve_reverse_ipv6()\fP\&.
371 .RE
372 .PP
373 .PP
374 \fBParameters:\fP
375 .RS 4
376 \fIin\fP an IPv6 address
377 .br
378 \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&.
379 .br
380 \fIcallback\fP a callback function to invoke when the request is completed
381 .br
382 \fIptr\fP an argument to pass to the callback function
383 .RE
384 .PP
385 \fBReturns:\fP
386 .RS 4
387 0 if successful, or -1 if an error occurred
388 .RE
389 .PP
390 \fBSee also:\fP
391 .RS 4
392 \fBevdns_resolve_reverse_ipv6()\fP
393 .RE
394 .PP
396 .SS "int evdns_resume (void)"
398 .PP
399 Resume normal operation and continue any suspended resolve requests\&. Re-attempt resolves left in limbo after an earlier call to \fBevdns_clear_nameservers_and_suspend()\fP\&.
400 .PP
401 \fBDeprecated\fP
402 .RS 4
403 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resume()\fP\&.
404 .RE
405 .PP
406 .PP
407 \fBReturns:\fP
408 .RS 4
409 0 if successful, or -1 if an error occurred
410 .RE
411 .PP
412 \fBSee also:\fP
413 .RS 4
414 \fBevdns_clear_nameservers_and_suspend()\fP
415 .RE
416 .PP
418 .SS "void evdns_search_add (const char *domain)"
420 .PP
421 Add a domain to the list of search domains\&.
422 .PP
423 \fBDeprecated\fP
424 .RS 4
425 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_search_add()\fP\&.
426 .RE
427 .PP
428 .PP
429 \fBParameters:\fP
430 .RS 4
431 \fIdomain\fP the domain to be added to the search list
432 .RE
433 .PP
435 .SS "void evdns_search_clear (void)"
437 .PP
438 Clear the list of search domains\&.
439 .PP
440 \fBDeprecated\fP
441 .RS 4
442 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_search_clear()\fP\&.
443 .RE
444 .PP
446 .SS "void evdns_search_ndots_set (const intndots)"
448 .PP
449 Set the 'ndots' parameter for searches\&. Sets the number of dots which, when found in a name, causes the first query to be without any search domain\&.
450 .PP
451 \fBDeprecated\fP
452 .RS 4
453 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_search_ndots_set()\fP\&.
454 .RE
455 .PP
456 .PP
457 \fBParameters:\fP
458 .RS 4
459 \fIndots\fP the new ndots parameter
460 .RE
461 .PP
463 .SS "int evdns_set_option (const char *option, const char *val, intflags)"
465 .PP
466 Set the value of a configuration option\&. The currently available configuration options are:
467 .PP
468 ndots, timeout, max-timeouts, max-inflight, and attempts
469 .PP
470 \fBDeprecated\fP
471 .RS 4
472 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_set_option()\fP\&.
473 .RE
474 .PP
475 .PP
476 \fBParameters:\fP
477 .RS 4
478 \fIoption\fP the name of the configuration option to be modified
479 .br
480 \fIval\fP the value to be set
481 .br
482 \fIflags\fP Ignored\&.
483 .RE
484 .PP
485 \fBReturns:\fP
486 .RS 4
487 0 if successful, or -1 if an error occurred
488 .RE
489 .PP
491 .SS "void evdns_shutdown (intfail_requests)"
493 .PP
494 Shut down the asynchronous DNS resolver and terminate all active requests\&. If the 'fail_requests' option is enabled, all active requests will return an empty result with the error flag set to DNS_ERR_SHUTDOWN\&. Otherwise, the requests will be silently discarded\&.
495 .PP
496 \fBDeprecated\fP
497 .RS 4
498 This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is evdns_base_shutdown()\&.
499 .RE
500 .PP
501 .PP
502 \fBParameters:\fP
503 .RS 4
504 \fIfail_requests\fP if zero, active requests will be aborted; if non-zero, active requests will return DNS_ERR_SHUTDOWN\&.
505 .RE
506 .PP
507 \fBSee also:\fP
508 .RS 4
509 \fBevdns_init()\fP
510 .RE
511 .PP
513 .SH "Author"
514 .PP
515 Generated automatically by Doxygen for libevent from the source code\&.