Index: third_party/libevent/evdns.3 |
diff --git a/third_party/libevent/evdns.3 b/third_party/libevent/evdns.3 |
deleted file mode 100644 |
index 10414fa2efbe803a744dc8126054fcb6c5778187..0000000000000000000000000000000000000000 |
--- a/third_party/libevent/evdns.3 |
+++ /dev/null |
@@ -1,322 +0,0 @@ |
-.\" |
-.\" Copyright (c) 2006 Niels Provos <provos@citi.umich.edu> |
-.\" All rights reserved. |
-.\" |
-.\" Redistribution and use in source and binary forms, with or without |
-.\" modification, are permitted provided that the following conditions |
-.\" are met: |
-.\" |
-.\" 1. Redistributions of source code must retain the above copyright |
-.\" notice, this list of conditions and the following disclaimer. |
-.\" 2. Redistributions in binary form must reproduce the above copyright |
-.\" notice, this list of conditions and the following disclaimer in the |
-.\" documentation and/or other materials provided with the distribution. |
-.\" 3. The name of the author may not be used to endorse or promote products |
-.\" derived from this software without specific prior written permission. |
-.\" |
-.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, |
-.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY |
-.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL |
-.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
-.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
-.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; |
-.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, |
-.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR |
-.\" 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 |
-Welcome, gentle reader |
-.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 |
-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 |
-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 |
-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 |
-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 |
-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 |
-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 |
-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 |
-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 |
-Quick start guide: |
- #include "evdns.h" |
- void callback(int result, char type, int count, int ttl, |
- void *addresses, void *arg); |
- evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf"); |
- evdns_resolve("www.hostname.com", 0, callback, NULL); |
-.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 |
-DNS_IPv4_A, count will be the number of IP addresses, ttl is the time |
-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 |
-Searching: |
-.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 |
-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 |
-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, |
-or |
-.Fn evdns_search_add |
-then no searching will occur. |
-.It |
-If you do call |
-.Fn evdns_resolv_conf_parse |
-then don't pass |
-.Va DNS_OPTION_SEARCH |
-(or |
-.Va DNS_OPTIONS_ALL, |
-which implies it). |
-.It |
-When calling |
-.Fn evdns_resolve, |
-pass the |
-.Va DNS_QUERY_NO_SEARCH |
-flag. |
-.El |
-.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 |
-The ndots setting can either be set from a resolv.conf, or by calling |
-evdns_search_ndots_set. |
-.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 |
- 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 |
-Initializes support for non-blocking name resolution by calling |
-.Fn evdns_resolv_conf_parse |
-on UNIX and |
-.Fn evdns_config_windows_nameservers |
-on Windows. |
-.It Ft int Fn evdns_nameserver_add "unsigned long int address" |
-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" |
-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" |
-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 |
-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 |
-Returns non-zero on error |
-.It Ft void Fn evdns_search_clear |
-Clears the list of search domains |
-.It Ft void Fn evdns_search_add "const char *domain" |
-Add a domain to the list of search domains |
-.It Ft void Fn evdns_search_ndots_set "int ndots" |
-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" |
-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" |
-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" |
-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" |
-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" |
-Parse a resolv.conf like file from the given filename. |
-.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 |
-domain, search and ndots options |
-.It DNS_OPTION_NAMESERVERS |
-nameserver lines |
-.It DNS_OPTION_MISC |
-timeout and attempts options |
-.It DNS_OPTIONS_ALL |
-all of the above |
-.El |
-.Pp |
-The following directives are not parsed from the file: |
- sortlist, rotate, no-check-names, inet6, debug |
-.Pp |
-Returns non-zero on error: |
-.Bl -tag -width "0" -offset indent -compact -nested |
-.It 0 |
-no errors |
-.It 1 |
-failed to open file |
-.It 2 |
-failed to stat file |
-.It 3 |
-file too large |
-.It 4 |
-out of memory |
-.It 5 |
-short read from file |
-.El |
-.El |
-.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 |
-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 |
-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 |
-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 |
-The |
-.Nm evdns |
-API was developed by Adam Langley on top of the |
-.Nm libevent |
-API. |
-The code was integrate into |
-.Nm Tor |
-by Nick Mathewson and finally put into |
-.Nm libevent |
-itself by Niels Provos. |
-.Sh AUTHORS |
-The |
-.Nm evdns |
-API and code was written by Adam Langley with significant |
-contributions by Nick Mathewson. |
-.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 |
-up the missing piece of documentation and send it to |
-me for inclusion in this man page. |