| blob | a5a2a75652f339c5da6ca4eed84fb19eabd8bce1 |
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