diff options
Diffstat (limited to 'libs/libevent/docs/evdns.3')
| -rw-r--r-- | libs/libevent/docs/evdns.3 | 322 |
1 files changed, 0 insertions, 322 deletions
diff --git a/libs/libevent/docs/evdns.3 b/libs/libevent/docs/evdns.3 deleted file mode 100644 index 10414fa2ef..0000000000 --- a/libs/libevent/docs/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. |