1 --- libevent-1.4.14b-stable/evdns.3 st lis 25 07:55:34 2009 |
|
2 +++ libevent-1.4.14b-stable/evdns.3 po lis 21 09:31:22 2011 |
|
3 @@ -25,66 +25,67 @@ |
|
4 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF |
|
5 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
6 .\" |
|
7 -.Dd October 7, 2006 |
|
8 -.Dt EVDNS 3 |
|
9 -.Os |
|
10 -.Sh NAME |
|
11 -.Nm evdns_init |
|
12 -.Nm evdns_shutdown |
|
13 -.Nm evdns_err_to_string |
|
14 -.Nm evdns_nameserver_add |
|
15 -.Nm evdns_count_nameservers |
|
16 -.Nm evdns_clear_nameservers_and_suspend |
|
17 -.Nm evdns_resume |
|
18 -.Nm evdns_nameserver_ip_add |
|
19 -.Nm evdns_resolve_ipv4 |
|
20 -.Nm evdns_resolve_reverse |
|
21 -.Nm evdns_resolv_conf_parse |
|
22 -.Nm evdns_config_windows_nameservers |
|
23 -.Nm evdns_search_clear |
|
24 -.Nm evdns_search_add |
|
25 -.Nm evdns_search_ndots_set |
|
26 -.Nm evdns_set_log_fn |
|
27 -.Nd asynchronous functions for DNS resolution. |
|
28 -.Sh SYNOPSIS |
|
29 -.Fd #include <sys/time.h> |
|
30 -.Fd #include <event.h> |
|
31 -.Fd #include <evdns.h> |
|
32 -.Ft int |
|
33 -.Fn evdns_init |
|
34 -.Ft void |
|
35 -.Fn evdns_shutdown "int fail_requests" |
|
36 -.Ft "const char *" |
|
37 -.Fn evdns_err_to_string "int err" |
|
38 -.Ft int |
|
39 -.Fn evdns_nameserver_add "unsigned long int address" |
|
40 -.Ft int |
|
41 -.Fn evdns_count_nameservers |
|
42 -.Ft int |
|
43 -.Fn evdns_clear_nameservers_and_suspend |
|
44 -.Ft int |
|
45 -.Fn evdns_resume |
|
46 -.Ft int |
|
47 -.Fn evdns_nameserver_ip_add(const char *ip_as_string); |
|
48 -.Ft int |
|
49 -.Fn evdns_resolve_ipv4 "const char *name" "int flags" "evdns_callback_type callback" "void *ptr" |
|
50 -.Ft int |
|
51 -.Fn evdns_resolve_reverse "struct in_addr *in" "int flags" "evdns_callback_type callback" "void *ptr" |
|
52 -.Ft int |
|
53 -.Fn evdns_resolv_conf_parse "int flags" "const char *" |
|
54 -.Ft void |
|
55 -.Fn evdns_search_clear |
|
56 -.Ft void |
|
57 -.Fn evdns_search_add "const char *domain" |
|
58 -.Ft void |
|
59 -.Fn evdns_search_ndots_set "const int ndots" |
|
60 -.Ft void |
|
61 -.Fn evdns_set_log_fn "evdns_debug_log_fn_type fn" |
|
62 -.Ft int |
|
63 -.Fn evdns_config_windows_nameservers |
|
64 -.Sh DESCRIPTION |
|
65 +.TH EVDNS 3 "21 November 2011" "libevent 1.4.14b" "libevent Manual" |
|
66 +.SH NAME |
|
67 +evdns_init, |
|
68 +evdns_shutdown, |
|
69 +evdns_err_to_string, |
|
70 +evdns_nameserver_add, |
|
71 +evdns_count_nameservers, |
|
72 +evdns_clear_nameservers_and_suspend, |
|
73 +evdns_resume, |
|
74 +evdns_nameserver_ip_add, |
|
75 +evdns_resolve_ipv4, |
|
76 +evdns_resolve_reverse, |
|
77 +evdns_resolv_conf_parse, |
|
78 +evdns_config_windows_nameservers, |
|
79 +evdns_search_clear, |
|
80 +evdns_search_add, |
|
81 +evdns_search_ndots_set, |
|
82 +evdns_set_log_fn |
|
83 +\- asynchronous functions for DNS resolution. |
|
84 +.SH SYNOPSIS |
|
85 +.LP |
|
86 +.nf |
|
87 +\fB#include <sys/time.h>\fP |
|
88 +\fB#include <event.h>\fP |
|
89 +\fB#include <evdns.h>\fP |
|
90 + |
|
91 +\fBinit \fBevdns_init\fR\fR(\fBvoid\fP\fR); |
|
92 + |
|
93 +\fBvoid \fBevdns_shutdown\fR\fR(\fBint \fIfail_requests\fP\fR); |
|
94 + |
|
95 +\fBconst char* \fBevdns_err_to_string\fR\fR(\fBint \fIerr\fP\fR); |
|
96 + |
|
97 +\fBint \fBevdns_nameserver_add\fR\fR(\fBunsigned long int \fIaddress\fP\fR); |
|
98 + |
|
99 +\fBint \fBevdns_count_nameservers\fR\fR(\fBvoid\fP\fR); |
|
100 + |
|
101 +\fBint \fBevdns_clear_nameservers_and_suspend\fR\fR(\fBvoid\fP\fR); |
|
102 + |
|
103 +\fBint \fBevdns_resume\fR\fR(\fBvoid\fP\fR); |
|
104 + |
|
105 +\fBint \fBevdns_nameserver_ip_add\fR\fR(\fBconst char* \fIip_as_string\fP\fR); |
|
106 + |
|
107 +\fBint \fBevdns_resolve_ipv4\fR\fR(\fBconst char* \fIname\fP\fR, \fBint \fIflags\fP\fR, \fBevdns_callback_type \fIcallback\fP\fR, \fBvoid* \fIptr\fP\fR); |
|
108 + |
|
109 +\fBint \fBevdns_resolve_reverse\fR\fR(\fBstruct in_addr* \fIin\fP\fR, \fBint \fIflags\fP\fR, \fBevdns_callback_type \fIcallback\fP\fR, \fBvoid* \fIptr\fP\fR); |
|
110 + |
|
111 +\fBint \fBevdns_resolv_conf_parse\fR\fR(\fBint \fIflags\fP\fR, \fBconst char* \fIfilename\fP\fR); |
|
112 + |
|
113 +\fBvoid \fBevdns_search_clear\fR\fR(\fBvoid\fP\fR); |
|
114 + |
|
115 +\fBvoid \fBevdns_search_add\fR\fR(\fBconst char* \fIdomain\fP\fR); |
|
116 + |
|
117 +\fBvoid \fBevdns_search_ndots_set\fR\fR(\fBconst int \fIndots\fP\fR); |
|
118 + |
|
119 +\fBvoid \fBevdns_set_log_fn\fR\fR(\fBcevdns_debug_log_fn_type \fIfn\fP\fR); |
|
120 + |
|
121 +\fBint \fBevdns_config_windows_nameservers\fR\fR(\fBvoid\fP\fR); |
|
122 +.fi |
|
123 +.SH DESCRIPTION |
|
124 Welcome, gentle reader |
|
125 -.Pp |
|
126 +.PP |
|
127 Async DNS lookups are really a whole lot harder than they should be, |
|
128 mostly stemming from the fact that the libc resolver has never been |
|
129 very good at them. Before you use this library you should see if libc |
|
130 @@ -91,37 +92,49 @@ |
|
131 can do the job for you with the modern async call getaddrinfo_a |
|
132 (see http://www.imperialviolet.org/page25.html#e498). Otherwise, |
|
133 please continue. |
|
134 -.Pp |
|
135 +.PP |
|
136 This code is based on libevent and you must call event_init before |
|
137 any of the APIs in this file. You must also seed the OpenSSL random |
|
138 source if you are using OpenSSL for ids (see below). |
|
139 -.Pp |
|
140 +.PP |
|
141 This library is designed to be included and shipped with your source |
|
142 code. You statically link with it. You should also test for the |
|
143 existence of strtok_r and define HAVE_STRTOK_R if you have it. |
|
144 -.Pp |
|
145 +.PP |
|
146 The DNS protocol requires a good source of id numbers and these |
|
147 numbers should be unpredictable for spoofing reasons. There are |
|
148 three methods for generating them here and you must define exactly |
|
149 one of them. In increasing order of preference: |
|
150 -.Pp |
|
151 -.Bl -tag -width "DNS_USE_GETTIMEOFDAY_FOR_ID" -compact -offset indent |
|
152 -.It DNS_USE_GETTIMEOFDAY_FOR_ID |
|
153 +.PP |
|
154 +DNS_USE_GETTIMEOFDAY_FOR_ID |
|
155 +.ad |
|
156 +.sp .6 |
|
157 +.RS 4n |
|
158 Using the bottom 16 bits of the usec result from gettimeofday. This |
|
159 is a pretty poor solution but should work anywhere. |
|
160 -.It DNS_USE_CPU_CLOCK_FOR_ID |
|
161 +.RE |
|
162 +.PP |
|
163 +DNS_USE_CPU_CLOCK_FOR_ID |
|
164 +.ad |
|
165 +.sp .6 |
|
166 +.RS 4n |
|
167 Using the bottom 16 bits of the nsec result from the CPU's time |
|
168 counter. This is better, but may not work everywhere. Requires |
|
169 POSIX realtime support and you'll need to link against -lrt on |
|
170 glibc systems at least. |
|
171 -.It DNS_USE_OPENSSL_FOR_ID |
|
172 +.RE |
|
173 +.PP |
|
174 +DNS_USE_OPENSSL_FOR_ID |
|
175 +.ad |
|
176 +.sp .6 |
|
177 +.RS 4n |
|
178 Uses the OpenSSL RAND_bytes call to generate the data. You must |
|
179 have seeded the pool before making any calls to this library. |
|
180 -.El |
|
181 -.Pp |
|
182 +.RE |
|
183 +.PP |
|
184 The library keeps track of the state of nameservers and will avoid |
|
185 them when they go down. Otherwise it will round robin between them. |
|
186 -.Pp |
|
187 +.PP |
|
188 Quick start guide: |
|
189 #include "evdns.h" |
|
190 void callback(int result, char type, int count, int ttl, |
|
191 @@ -128,7 +141,7 @@ |
|
192 void *addresses, void *arg); |
|
193 evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf"); |
|
194 evdns_resolve("www.hostname.com", 0, callback, NULL); |
|
195 -.Pp |
|
196 +.PP |
|
197 When the lookup is complete the callback function is called. The |
|
198 first argument will be one of the DNS_ERR_* defines in evdns.h. |
|
199 Hopefully it will be DNS_ERR_NONE, in which case type will be |
|
200 @@ -136,152 +149,187 @@ |
|
201 which the data can be cached for (in seconds), addresses will point |
|
202 to an array of uint32_t's and arg will be whatever you passed to |
|
203 evdns_resolve. |
|
204 -.Pp |
|
205 +.PP |
|
206 Searching: |
|
207 -.Pp |
|
208 +.PP |
|
209 In order for this library to be a good replacement for glibc's resolver it |
|
210 supports searching. This involves setting a list of default domains, in |
|
211 which names will be queried for. The number of dots in the query name |
|
212 determines the order in which this list is used. |
|
213 -.Pp |
|
214 +.PP |
|
215 Searching appears to be a single lookup from the point of view of the API, |
|
216 although many DNS queries may be generated from a single call to |
|
217 evdns_resolve. Searching can also drastically slow down the resolution |
|
218 of names. |
|
219 -.Pp |
|
220 +.PP |
|
221 To disable searching: |
|
222 -.Bl -enum -compact -offset indent |
|
223 -.It |
|
224 -Never set it up. If you never call |
|
225 -.Fn evdns_resolv_conf_parse, |
|
226 -.Fn evdns_init, |
|
227 +.ad |
|
228 +.sp .6 |
|
229 +.RS 4n |
|
230 +1. Never set it up. If you never call |
|
231 +\fBevdns_resolv_conf_parse\fP\fR, |
|
232 +\fBevdns_init\fP\fR, |
|
233 or |
|
234 -.Fn evdns_search_add |
|
235 +\fBevdns_search_add\fP\R |
|
236 then no searching will occur. |
|
237 -.It |
|
238 -If you do call |
|
239 -.Fn evdns_resolv_conf_parse |
|
240 +.br |
|
241 +2. If you do call |
|
242 +\fBevdns_resolv_conf_parse\fP\fR |
|
243 then don't pass |
|
244 -.Va DNS_OPTION_SEARCH |
|
245 +DNS_OPTION_SEARCH |
|
246 (or |
|
247 -.Va DNS_OPTIONS_ALL, |
|
248 +DNS_OPTIONS_ALL, |
|
249 which implies it). |
|
250 -.It |
|
251 -When calling |
|
252 -.Fn evdns_resolve, |
|
253 +.br |
|
254 +3. When calling |
|
255 +\fBevdns_resolve\fP\fR, |
|
256 pass the |
|
257 -.Va DNS_QUERY_NO_SEARCH |
|
258 +DNS_QUERY_NO_SEARCH |
|
259 flag. |
|
260 -.El |
|
261 -.Pp |
|
262 +.RE |
|
263 +.PP |
|
264 The order of searches depends on the number of dots in the name. If the |
|
265 number is greater than the ndots setting then the names is first tried |
|
266 globally. Otherwise each search domain is appended in turn. |
|
267 -.Pp |
|
268 +.PP |
|
269 The ndots setting can either be set from a resolv.conf, or by calling |
|
270 evdns_search_ndots_set. |
|
271 -.Pp |
|
272 +.PP |
|
273 For example, with ndots set to 1 (the default) and a search domain list of |
|
274 ["myhome.net"]: |
|
275 Query: www |
|
276 Order: www.myhome.net, www. |
|
277 -.Pp |
|
278 +.PP |
|
279 Query: www.abc |
|
280 Order: www.abc., www.abc.myhome.net |
|
281 -.Pp |
|
282 -.Sh API reference |
|
283 -.Pp |
|
284 -.Bl -tag -width 0123456 |
|
285 -.It Ft int Fn evdns_init |
|
286 +.PP |
|
287 +.SH API reference |
|
288 +.PP |
|
289 +.SS "\fBint \fBevdns_init\fR\fR(\fBvoid\fP\fR)" |
|
290 +.sp |
|
291 +.LP |
|
292 Initializes support for non-blocking name resolution by calling |
|
293 -.Fn evdns_resolv_conf_parse |
|
294 +evdns_resolv_conf_parse() |
|
295 on UNIX and |
|
296 -.Fn evdns_config_windows_nameservers |
|
297 +evdns_config_windows_nameservers() |
|
298 on Windows. |
|
299 -.It Ft int Fn evdns_nameserver_add "unsigned long int address" |
|
300 +.SS "\fBint \fBevdns_nameserver_add\fR\fR(\fBunsigned long int\fP\fR \fIaddress\fP\fR)" |
|
301 +.sp |
|
302 +.LP |
|
303 Add a nameserver. The address should be an IP address in |
|
304 network byte order. The type of address is chosen so that |
|
305 it matches in_addr.s_addr. |
|
306 Returns non-zero on error. |
|
307 -.It Ft int Fn evdns_nameserver_ip_add "const char *ip_as_string" |
|
308 +.SS "\fBint \fBevdns_nameserver_ip_add\fR\fR(\fBconst char* \fIip_as_string\fP\fR)" |
|
309 +.sp |
|
310 +.LP |
|
311 This wraps the above function by parsing a string as an IP |
|
312 address and adds it as a nameserver. |
|
313 Returns non-zero on error |
|
314 -.It Ft int Fn evdns_resolve "const char *name" "int flags" "evdns_callback_type callback" "void *ptr" |
|
315 +.SS "\fBint \fBevdns_resolve\fR\fR(\fBconst char* \fIname\fP\fR, \fBint \fIflags\fP\fR, \fBevdns_callback_type \fIcallback\fP\fR, \fBvoid* \fIptr\fP\fR)" |
|
316 +.sp |
|
317 +.LP |
|
318 Resolve a name. The name parameter should be a DNS name. |
|
319 The flags parameter should be 0, or DNS_QUERY_NO_SEARCH |
|
320 which disables searching for this query. (see defn of |
|
321 searching above). |
|
322 -.Pp |
|
323 +.PP |
|
324 The callback argument is a function which is called when |
|
325 this query completes and ptr is an argument which is passed |
|
326 to that callback function. |
|
327 -.Pp |
|
328 +.PP |
|
329 Returns non-zero on error |
|
330 -.It Ft void Fn evdns_search_clear |
|
331 +.SS "\fBvoid \fBevdns_search_clear\fR\fR(\fBvoid\fP\fR)" |
|
332 +.sp |
|
333 +.LP |
|
334 Clears the list of search domains |
|
335 -.It Ft void Fn evdns_search_add "const char *domain" |
|
336 +.SS "\fBvoid \fBevdns_search_add\fR\fR(\fBconst char* \fIdomain\fP\fR)" |
|
337 +.sp |
|
338 +.LP |
|
339 Add a domain to the list of search domains |
|
340 -.It Ft void Fn evdns_search_ndots_set "int ndots" |
|
341 +.SS "\fBvoid \fBevdns_search_ndots_set\fR\fR(\fBconst int \fIndots\fP\fR)" |
|
342 +.sp |
|
343 +.LP |
|
344 Set the number of dots which, when found in a name, causes |
|
345 the first query to be without any search domain. |
|
346 -.It Ft int Fn evdns_count_nameservers "void" |
|
347 +.SS "\fBint \fBevdns_count_nameservers\fR\fR(\fBvoid\fP\fR)" |
|
348 +.sp |
|
349 +.LP |
|
350 Return the number of configured nameservers (not necessarily the |
|
351 number of running nameservers). This is useful for double-checking |
|
352 whether our calls to the various nameserver configuration functions |
|
353 have been successful. |
|
354 -.It Ft int Fn evdns_clear_nameservers_and_suspend "void" |
|
355 +.SS "\fBint \fBevdns_clear_nameservers_and_suspend\fR\fR(\fBvoid\fP\fR)" |
|
356 +.sp |
|
357 +.LP |
|
358 Remove all currently configured nameservers, and suspend all pending |
|
359 resolves. Resolves will not necessarily be re-attempted until |
|
360 evdns_resume() is called. |
|
361 -.It Ft int Fn evdns_resume "void" |
|
362 +.SS "\fBint \fBevdns_resume\fR\fR(\fBvoid\fP\fR)" |
|
363 +.sp |
|
364 +.LP |
|
365 Re-attempt resolves left in limbo after an earlier call to |
|
366 evdns_clear_nameservers_and_suspend(). |
|
367 -.It Ft int Fn evdns_config_windows_nameservers "void" |
|
368 +.SS "\fBint \fBevdns_config_windows_nameservers\fR\fR(\fBvoid\fP\fR)" |
|
369 +.sp |
|
370 +.LP |
|
371 Attempt to configure a set of nameservers based on platform settings on |
|
372 a win32 host. Preferentially tries to use GetNetworkParams; if that fails, |
|
373 looks in the registry. Returns 0 on success, nonzero on failure. |
|
374 -.It Ft int Fn evdns_resolv_conf_parse "int flags" "const char *filename" |
|
375 +.SS "\fBint \fBevdns_resolv_conf_parse\fR\fR(\fBint \fIflags\fP\fR, \fBconst char*filename\fP\fR)" |
|
376 +.sp |
|
377 +.LP |
|
378 Parse a resolv.conf like file from the given filename. |
|
379 -.Pp |
|
380 +.PP |
|
381 See the man page for resolv.conf for the format of this file. |
|
382 The flags argument determines what information is parsed from |
|
383 this file: |
|
384 -.Bl -tag -width "DNS_OPTION_NAMESERVERS" -offset indent -compact -nested |
|
385 -.It DNS_OPTION_SEARCH |
|
386 +.sp |
|
387 +DNS_OPTION_SEARCH |
|
388 domain, search and ndots options |
|
389 -.It DNS_OPTION_NAMESERVERS |
|
390 +.br |
|
391 +DNS_OPTION_NAMESERVERS |
|
392 nameserver lines |
|
393 -.It DNS_OPTION_MISC |
|
394 +.br |
|
395 +DNS_OPTION_MISC |
|
396 timeout and attempts options |
|
397 -.It DNS_OPTIONS_ALL |
|
398 +.br |
|
399 +DNS_OPTIONS_ALL |
|
400 all of the above |
|
401 -.El |
|
402 -.Pp |
|
403 +.PP |
|
404 The following directives are not parsed from the file: |
|
405 sortlist, rotate, no-check-names, inet6, debug |
|
406 -.Pp |
|
407 +.PP |
|
408 Returns non-zero on error: |
|
409 -.Bl -tag -width "0" -offset indent -compact -nested |
|
410 -.It 0 |
|
411 +.sp |
|
412 +0 |
|
413 +.br |
|
414 no errors |
|
415 -.It 1 |
|
416 +.br |
|
417 +1 |
|
418 +.br |
|
419 failed to open file |
|
420 -.It 2 |
|
421 +.br |
|
422 +2 |
|
423 +.br |
|
424 failed to stat file |
|
425 -.It 3 |
|
426 +.br |
|
427 +3 |
|
428 +.br |
|
429 file too large |
|
430 -.It 4 |
|
431 +.br |
|
432 +4 |
|
433 +.br |
|
434 out of memory |
|
435 -.It 5 |
|
436 +.br |
|
437 +5 |
|
438 +.br |
|
439 short read from file |
|
440 -.El |
|
441 -.El |
|
442 -.Sh Internals: |
|
443 +.SH Internals: |
|
444 Requests are kept in two queues. The first is the inflight queue. In |
|
445 this queue requests have an allocated transaction id and nameserver. |
|
446 They will soon be transmitted if they haven't already been. |
|
447 -.Pp |
|
448 +.PP |
|
449 The second is the waiting queue. The size of the inflight ring is |
|
450 limited and all other requests wait in waiting queue for space. This |
|
451 bounds the number of concurrent requests so that we don't flood the |
|
452 @@ -288,33 +336,33 @@ |
|
453 nameserver. Several algorithms require a full walk of the inflight |
|
454 queue and so bounding its size keeps thing going nicely under huge |
|
455 (many thousands of requests) loads. |
|
456 -.Pp |
|
457 +.PP |
|
458 If a nameserver loses too many requests it is considered down and we |
|
459 try not to use it. After a while we send a probe to that nameserver |
|
460 (a lookup for google.com) and, if it replies, we consider it working |
|
461 again. If the nameserver fails a probe we wait longer to try again |
|
462 with the next probe. |
|
463 -.Sh SEE ALSO |
|
464 -.Xr event 3 , |
|
465 -.Xr gethostbyname 3 , |
|
466 -.Xr resolv.conf 5 |
|
467 -.Sh HISTORY |
|
468 +.SH SEE ALSO |
|
469 +\fBevent(3)\fR, |
|
470 +\fBgethostbyname(3)\fR, |
|
471 +\fBresolv.conf(4)\fR |
|
472 +.SH HISTORY |
|
473 The |
|
474 -.Nm evdns |
|
475 +\fIevdns\fP\fR |
|
476 API was developed by Adam Langley on top of the |
|
477 -.Nm libevent |
|
478 +\fIlibevent\fP\fR |
|
479 API. |
|
480 The code was integrate into |
|
481 -.Nm Tor |
|
482 +\fITor\fP\fR |
|
483 by Nick Mathewson and finally put into |
|
484 -.Nm libevent |
|
485 +\fIlibevent\fP\fR |
|
486 itself by Niels Provos. |
|
487 -.Sh AUTHORS |
|
488 +.SH AUTHORS |
|
489 The |
|
490 -.Nm evdns |
|
491 +\fIevdns\fP\fR |
|
492 API and code was written by Adam Langley with significant |
|
493 contributions by Nick Mathewson. |
|
494 -.Sh BUGS |
|
495 +.SH BUGS |
|
496 This documentation is neither complete nor authoritative. |
|
497 If you are in doubt about the usage of this API then |
|
498 check the source code to find out how it works, write |
|