move libevent into base

third_party/libevent/evdns.3

-.\"
-.\" 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.