components/libevent/patches/evdns.3.patch
changeset 604 c25824a87b1f
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/components/libevent/patches/evdns.3.patch	Wed Nov 30 06:39:13 2011 -0800
@@ -0,0 +1,498 @@
+--- libevent-1.4.14b-stable/evdns.3	st lis 25 07:55:34 2009
++++ libevent-1.4.14b-stable/evdns.3	po lis 21 09:31:22 2011
[email protected]@ -25,66 +25,67 @@
+ .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ .\"
+-.Dd October 7, 2006
+-.Dt EVDNS 3
+-.Os
+-.Sh NAME
+-.Nm evdns_init
+-.Nm evdns_shutdown
+-.Nm evdns_err_to_string
+-.Nm evdns_nameserver_add
+-.Nm evdns_count_nameservers
+-.Nm evdns_clear_nameservers_and_suspend
+-.Nm evdns_resume
+-.Nm evdns_nameserver_ip_add
+-.Nm evdns_resolve_ipv4
+-.Nm evdns_resolve_reverse
+-.Nm evdns_resolv_conf_parse
+-.Nm evdns_config_windows_nameservers
+-.Nm evdns_search_clear
+-.Nm evdns_search_add
+-.Nm evdns_search_ndots_set
+-.Nm evdns_set_log_fn
+-.Nd asynchronous functions for DNS resolution.
+-.Sh SYNOPSIS
+-.Fd #include <sys/time.h>
+-.Fd #include <event.h>
+-.Fd #include <evdns.h>
+-.Ft int
+-.Fn evdns_init
+-.Ft void
+-.Fn evdns_shutdown "int fail_requests"
+-.Ft "const char *"
+-.Fn evdns_err_to_string "int err"
+-.Ft int
+-.Fn evdns_nameserver_add "unsigned long int address"
+-.Ft int
+-.Fn evdns_count_nameservers
+-.Ft int
+-.Fn evdns_clear_nameservers_and_suspend
+-.Ft int
+-.Fn evdns_resume
+-.Ft int
+-.Fn evdns_nameserver_ip_add(const char *ip_as_string);
+-.Ft int
+-.Fn evdns_resolve_ipv4 "const char *name" "int flags" "evdns_callback_type callback" "void *ptr"
+-.Ft int
+-.Fn evdns_resolve_reverse "struct in_addr *in" "int flags" "evdns_callback_type callback" "void *ptr"
+-.Ft int
+-.Fn evdns_resolv_conf_parse "int flags" "const char *"
+-.Ft void
+-.Fn evdns_search_clear
+-.Ft void
+-.Fn evdns_search_add "const char *domain"
+-.Ft void
+-.Fn evdns_search_ndots_set "const int ndots"
+-.Ft void
+-.Fn evdns_set_log_fn "evdns_debug_log_fn_type fn"
+-.Ft int
+-.Fn evdns_config_windows_nameservers
+-.Sh DESCRIPTION
++.TH EVDNS 3 "21 November 2011" "libevent 1.4.14b" "libevent Manual"
++.SH NAME
++evdns_init,
++evdns_shutdown,
++evdns_err_to_string,
++evdns_nameserver_add,
++evdns_count_nameservers,
++evdns_clear_nameservers_and_suspend,
++evdns_resume,
++evdns_nameserver_ip_add,
++evdns_resolve_ipv4,
++evdns_resolve_reverse,
++evdns_resolv_conf_parse,
++evdns_config_windows_nameservers,
++evdns_search_clear,
++evdns_search_add,
++evdns_search_ndots_set,
++evdns_set_log_fn
++\- asynchronous functions for DNS resolution.
++.SH SYNOPSIS
++.LP
++.nf
++\fB#include <sys/time.h>\fP
++\fB#include <event.h>\fP
++\fB#include <evdns.h>\fP
++
++\fBinit \fBevdns_init\fR\fR(\fBvoid\fP\fR);
++
++\fBvoid \fBevdns_shutdown\fR\fR(\fBint \fIfail_requests\fP\fR);
++
++\fBconst char* \fBevdns_err_to_string\fR\fR(\fBint \fIerr\fP\fR);
++
++\fBint \fBevdns_nameserver_add\fR\fR(\fBunsigned long int \fIaddress\fP\fR);
++
++\fBint \fBevdns_count_nameservers\fR\fR(\fBvoid\fP\fR);
++
++\fBint \fBevdns_clear_nameservers_and_suspend\fR\fR(\fBvoid\fP\fR);
++
++\fBint \fBevdns_resume\fR\fR(\fBvoid\fP\fR);
++
++\fBint \fBevdns_nameserver_ip_add\fR\fR(\fBconst char* \fIip_as_string\fP\fR);
++
++\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);
++
++\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);
++
++\fBint \fBevdns_resolv_conf_parse\fR\fR(\fBint \fIflags\fP\fR, \fBconst char* \fIfilename\fP\fR);
++
++\fBvoid \fBevdns_search_clear\fR\fR(\fBvoid\fP\fR);
++
++\fBvoid \fBevdns_search_add\fR\fR(\fBconst char* \fIdomain\fP\fR);
++
++\fBvoid \fBevdns_search_ndots_set\fR\fR(\fBconst int \fIndots\fP\fR);
++
++\fBvoid \fBevdns_set_log_fn\fR\fR(\fBcevdns_debug_log_fn_type \fIfn\fP\fR);
++
++\fBint \fBevdns_config_windows_nameservers\fR\fR(\fBvoid\fP\fR);
++.fi
++.SH DESCRIPTION
+ Welcome, gentle reader
+-.Pp
++.PP
+ Async DNS lookups are really a whole lot harder than they should be,
+ mostly stemming from the fact that the libc resolver has never been
+ very good at them. Before you use this library you should see if libc
[email protected]@ -91,37 +92,49 @@
+ can do the job for you with the modern async call getaddrinfo_a
+ (see http://www.imperialviolet.org/page25.html#e498). Otherwise,
+ please continue.
+-.Pp
++.PP
+ This code is based on libevent and you must call event_init before
+ any of the APIs in this file. You must also seed the OpenSSL random
+ source if you are using OpenSSL for ids (see below).
+-.Pp
++.PP
+ This library is designed to be included and shipped with your source
+ code. You statically link with it. You should also test for the
+ existence of strtok_r and define HAVE_STRTOK_R if you have it.
+-.Pp
++.PP
+ The DNS protocol requires a good source of id numbers and these
+ numbers should be unpredictable for spoofing reasons. There are
+ three methods for generating them here and you must define exactly
+ one of them. In increasing order of preference:
+-.Pp
+-.Bl -tag -width "DNS_USE_GETTIMEOFDAY_FOR_ID" -compact -offset indent
+-.It DNS_USE_GETTIMEOFDAY_FOR_ID
++.PP
++DNS_USE_GETTIMEOFDAY_FOR_ID
++.ad
++.sp .6
++.RS 4n
+ Using the bottom 16 bits of the usec result from gettimeofday. This
+ is a pretty poor solution but should work anywhere.
+-.It DNS_USE_CPU_CLOCK_FOR_ID
++.RE
++.PP
++DNS_USE_CPU_CLOCK_FOR_ID
++.ad
++.sp .6
++.RS 4n
+ Using the bottom 16 bits of the nsec result from the CPU's time
+ counter. This is better, but may not work everywhere. Requires
+ POSIX realtime support and you'll need to link against -lrt on
+ glibc systems at least.
+-.It DNS_USE_OPENSSL_FOR_ID
++.RE
++.PP
++DNS_USE_OPENSSL_FOR_ID
++.ad
++.sp .6
++.RS 4n
+ Uses the OpenSSL RAND_bytes call to generate the data. You must
+ have seeded the pool before making any calls to this library.
+-.El
+-.Pp
++.RE
++.PP
+ The library keeps track of the state of nameservers and will avoid
+ them when they go down. Otherwise it will round robin between them.
+-.Pp
++.PP
+ Quick start guide:
+   #include "evdns.h"
+   void callback(int result, char type, int count, int ttl,
[email protected]@ -128,7 +141,7 @@
+ 	 void *addresses, void *arg);
+   evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf");
+   evdns_resolve("www.hostname.com", 0, callback, NULL);
+-.Pp
++.PP
+ When the lookup is complete the callback function is called. The
+ first argument will be one of the DNS_ERR_* defines in evdns.h.
+ Hopefully it will be DNS_ERR_NONE, in which case type will be
[email protected]@ -136,152 +149,187 @@
+ which the data can be cached for (in seconds), addresses will point
+ to an array of uint32_t's and arg will be whatever you passed to
+ evdns_resolve.
+-.Pp
++.PP
+ Searching:
+-.Pp
++.PP
+ In order for this library to be a good replacement for glibc's resolver it
+ supports searching. This involves setting a list of default domains, in
+ which names will be queried for. The number of dots in the query name
+ determines the order in which this list is used.
+-.Pp
++.PP
+ Searching appears to be a single lookup from the point of view of the API,
+ although many DNS queries may be generated from a single call to
+ evdns_resolve. Searching can also drastically slow down the resolution
+ of names.
+-.Pp
++.PP
+ To disable searching:
+-.Bl -enum -compact -offset indent
+-.It
+-Never set it up. If you never call
+-.Fn evdns_resolv_conf_parse,
+-.Fn evdns_init,
++.ad
++.sp .6
++.RS 4n
++1. Never set it up. If you never call
++\fBevdns_resolv_conf_parse\fP\fR,
++\fBevdns_init\fP\fR,
+ or
+-.Fn evdns_search_add
++\fBevdns_search_add\fP\R
+ then no searching will occur.
+-.It
+-If you do call
+-.Fn evdns_resolv_conf_parse
++.br
++2. If you do call
++\fBevdns_resolv_conf_parse\fP\fR
+ then don't pass
+-.Va DNS_OPTION_SEARCH
++DNS_OPTION_SEARCH
+ (or
+-.Va DNS_OPTIONS_ALL,
++DNS_OPTIONS_ALL,
+ which implies it).
+-.It
+-When calling
+-.Fn evdns_resolve,
++.br
++3. When calling
++\fBevdns_resolve\fP\fR,
+ pass the
+-.Va DNS_QUERY_NO_SEARCH
++DNS_QUERY_NO_SEARCH
+ flag.
+-.El
+-.Pp
++.RE
++.PP
+ The order of searches depends on the number of dots in the name. If the
+ number is greater than the ndots setting then the names is first tried
+ globally. Otherwise each search domain is appended in turn.
+-.Pp
++.PP
+ The ndots setting can either be set from a resolv.conf, or by calling
+ evdns_search_ndots_set.
+-.Pp
++.PP
+ For example, with ndots set to 1 (the default) and a search domain list of
+ ["myhome.net"]:
+  Query: www
+  Order: www.myhome.net, www.
+-.Pp
++.PP
+  Query: www.abc
+  Order: www.abc., www.abc.myhome.net
+-.Pp
+-.Sh API reference
+-.Pp
+-.Bl -tag -width 0123456
+-.It Ft int Fn evdns_init
++.PP
++.SH API reference
++.PP
++.SS "\fBint \fBevdns_init\fR\fR(\fBvoid\fP\fR)"
++.sp
++.LP
+ Initializes support for non-blocking name resolution by calling
+-.Fn evdns_resolv_conf_parse
++evdns_resolv_conf_parse()
+ on UNIX and
+-.Fn evdns_config_windows_nameservers
++evdns_config_windows_nameservers()
+ on Windows.
+-.It Ft int Fn evdns_nameserver_add "unsigned long int address"
++.SS "\fBint \fBevdns_nameserver_add\fR\fR(\fBunsigned long int\fP\fR \fIaddress\fP\fR)"
++.sp
++.LP
+ Add a nameserver. The address should be an IP address in
+ network byte order. The type of address is chosen so that
+ it matches in_addr.s_addr.
+ Returns non-zero on error.
+-.It Ft int Fn evdns_nameserver_ip_add "const char *ip_as_string"
++.SS "\fBint \fBevdns_nameserver_ip_add\fR\fR(\fBconst char* \fIip_as_string\fP\fR)"
++.sp
++.LP
+ This wraps the above function by parsing a string as an IP
+ address and adds it as a nameserver.
+ Returns non-zero on error
+-.It Ft int Fn evdns_resolve "const char *name" "int flags" "evdns_callback_type callback" "void *ptr"
++.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)"
++.sp
++.LP
+ Resolve a name. The name parameter should be a DNS name.
+ The flags parameter should be 0, or DNS_QUERY_NO_SEARCH
+ which disables searching for this query. (see defn of
+ searching above).
+-.Pp
++.PP
+ The callback argument is a function which is called when
+ this query completes and ptr is an argument which is passed
+ to that callback function.
+-.Pp
++.PP
+ Returns non-zero on error
+-.It Ft void Fn evdns_search_clear
++.SS "\fBvoid \fBevdns_search_clear\fR\fR(\fBvoid\fP\fR)"
++.sp
++.LP
+ Clears the list of search domains
+-.It Ft void Fn evdns_search_add "const char *domain"
++.SS "\fBvoid \fBevdns_search_add\fR\fR(\fBconst char* \fIdomain\fP\fR)"
++.sp
++.LP
+ Add a domain to the list of search domains
+-.It Ft void Fn evdns_search_ndots_set "int ndots"
++.SS "\fBvoid \fBevdns_search_ndots_set\fR\fR(\fBconst int \fIndots\fP\fR)"
++.sp
++.LP
+ Set the number of dots which, when found in a name, causes
+ the first query to be without any search domain.
+-.It Ft int Fn evdns_count_nameservers "void"
++.SS "\fBint \fBevdns_count_nameservers\fR\fR(\fBvoid\fP\fR)"
++.sp
++.LP
+ Return 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.
+-.It Ft int Fn evdns_clear_nameservers_and_suspend "void"
++.SS "\fBint \fBevdns_clear_nameservers_and_suspend\fR\fR(\fBvoid\fP\fR)"
++.sp
++.LP
+ Remove all currently configured nameservers, and suspend all pending
+ resolves.  Resolves will not necessarily be re-attempted until
+ evdns_resume() is called.
+-.It Ft int Fn evdns_resume "void"
++.SS "\fBint \fBevdns_resume\fR\fR(\fBvoid\fP\fR)"
++.sp
++.LP
+ Re-attempt resolves left in limbo after an earlier call to
+ evdns_clear_nameservers_and_suspend().
+-.It Ft int Fn evdns_config_windows_nameservers "void"
++.SS "\fBint \fBevdns_config_windows_nameservers\fR\fR(\fBvoid\fP\fR)"
++.sp
++.LP
+ Attempt to configure a set of nameservers based on platform settings on
+ a win32 host.  Preferentially tries to use GetNetworkParams; if that fails,
+ looks in the registry.  Returns 0 on success, nonzero on failure.
+-.It Ft int Fn evdns_resolv_conf_parse "int flags" "const char *filename"
++.SS "\fBint \fBevdns_resolv_conf_parse\fR\fR(\fBint \fIflags\fP\fR, \fBconst char*filename\fP\fR)"
++.sp
++.LP
+ Parse a resolv.conf like file from the given filename.
+-.Pp
++.PP
+ See the man page for resolv.conf for the format of this file.
+ The flags argument determines what information is parsed from
+ this file:
+-.Bl -tag -width "DNS_OPTION_NAMESERVERS" -offset indent -compact -nested
+-.It DNS_OPTION_SEARCH
++.sp
++DNS_OPTION_SEARCH
+ domain, search and ndots options
+-.It DNS_OPTION_NAMESERVERS
++.br
++DNS_OPTION_NAMESERVERS
+ nameserver lines
+-.It DNS_OPTION_MISC
++.br
++DNS_OPTION_MISC
+ timeout and attempts options
+-.It DNS_OPTIONS_ALL
++.br
++DNS_OPTIONS_ALL
+ all of the above
+-.El
+-.Pp
++.PP
+ The following directives are not parsed from the file:
+   sortlist, rotate, no-check-names, inet6, debug
+-.Pp
++.PP
+ Returns non-zero on error:
+-.Bl -tag -width "0" -offset indent -compact -nested
+-.It 0
++.sp
++0
++.br
+ no errors
+-.It 1
++.br
++1
++.br
+ failed to open file
+-.It 2
++.br
++2
++.br
+ failed to stat file
+-.It 3
++.br
++3
++.br
+ file too large
+-.It 4
++.br
++4
++.br
+ out of memory
+-.It 5
++.br
++5
++.br
+ short read from file
+-.El
+-.El
+-.Sh Internals:
++.SH Internals:
+ Requests are kept in two queues. The first is the inflight queue. In
+ this queue requests have an allocated transaction id and nameserver.
+ They will soon be transmitted if they haven't already been.
+-.Pp
++.PP
+ The second is the waiting queue. The size of the inflight ring is
+ limited and all other requests wait in waiting queue for space. This
+ bounds the number of concurrent requests so that we don't flood the
[email protected]@ -288,33 +336,33 @@
+ nameserver. Several algorithms require a full walk of the inflight
+ queue and so bounding its size keeps thing going nicely under huge
+ (many thousands of requests) loads.
+-.Pp
++.PP
+ If a nameserver loses too many requests it is considered down and we
+ try not to use it. After a while we send a probe to that nameserver
+ (a lookup for google.com) and, if it replies, we consider it working
+ again. If the nameserver fails a probe we wait longer to try again
+ with the next probe.
+-.Sh SEE ALSO
+-.Xr event 3 ,
+-.Xr gethostbyname 3 ,
+-.Xr resolv.conf 5
+-.Sh HISTORY
++.SH SEE ALSO
++\fBevent(3)\fR,
++\fBgethostbyname(3)\fR,
++\fBresolv.conf(4)\fR
++.SH HISTORY
+ The
+-.Nm evdns
++\fIevdns\fP\fR
+ API was developed by Adam Langley on top of the
+-.Nm libevent
++\fIlibevent\fP\fR
+ API.
+ The code was integrate into
+-.Nm Tor
++\fITor\fP\fR
+ by Nick Mathewson and finally put into
+-.Nm libevent
++\fIlibevent\fP\fR
+ itself by Niels Provos.
+-.Sh AUTHORS
++.SH AUTHORS
+ The
+-.Nm evdns
++\fIevdns\fP\fR
+ API and code was written by Adam Langley with significant
+ contributions by Nick Mathewson.
+-.Sh BUGS
++.SH BUGS
+ This documentation is neither complete nor authoritative.
+ If you are in doubt about the usage of this API then
+ check the source code to find out how it works, write