clean up this page;

1 files changed, 113 insertions, 79 deletions

diff --git a/lib/libevent/evdns.3 b/lib/libevent/evdns.3
index 2a8ac5632d1..9c22c541203 100644
--- a/lib/libevent/evdns.3
+++ b/lib/libevent/evdns.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: evdns.3,v 1.1 2007/03/19 15:12:49 millert Exp $
+.\"	$OpenBSD: evdns.3,v 1.2 2007/03/19 20:12:45 jmc Exp $
 .\"
 .\" Copyright (c) 2006 Niels Provos <provos@citi.umich.edu>
 .\" All rights reserved.
@@ -45,7 +45,7 @@
 .Nm evdns_search_add
 .Nm evdns_search_ndots_set
 .Nm evdns_set_log_fn
-.Nd asynchronous functions for DNS resolution.
+.Nd asynchronous functions for DNS resolution
 .Sh SYNOPSIS
 .Fd #include <sys/time.h>
 .Fd #include <event.h>
@@ -81,17 +81,21 @@
 .Ft void
 .Fn evdns_set_log_fn "evdns_debug_log_fn_type fn"
 .Sh DESCRIPTION
-Welcome, gentle reader
+Welcome, gentle reader.
 .Pp
-Async DNS lookups are really a whole lot harder than they should be,
+Asynchronous 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
+can do the job for you with the modern async call
+.Fn 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
+This code is based on libevent and
+.Fn event_init
+must be called before
 any of the APIs in this file.
 .Pp
 The library keeps track of the state of nameservers and will avoid
@@ -108,17 +112,26 @@ evdns_resolve("www.hostname.com", 0, callback, NULL);
 .Ed
 .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.
+The first argument will be one of the DNS_ERR_* defines in
+.Aq Pa evdns.h .
+Hopefully it will be
+.Dv DNS_ERR_NONE ,
+in which case type will be
+.Dv DNS_IPv4_A ,
+.Fa count
+will be the number of IP addresses,
+.Fa ttl
+is the time which the data can be cached for (in seconds),
+.Fa addresses
+will point to an array of uint32_t's and
+.Fa arg
+will be whatever was passed to
+.Fn evdns_resolve .
 .Pp
 Searching:
 .Pp
-In order for this library to be a good replacement for the libc resolver it
-supports searching.
+In order for this library to be a good replacement for the libc 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
@@ -126,32 +139,34 @@ 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.
+.Fn evdns_resolve .
 Searching can also drastically slow down the resolution of names.
 .Pp
 To disable searching:
+.Pp
 .Bl -enum -compact -offset indent
 .It
 Never set it up.
-If you never call
-.Fn evdns_resolv_conf_parse,
-.Fn evdns_init,
-or
+If
+.Fn evdns_resolv_conf_parse ,
+.Fn evdns_init ,
+and
 .Fn evdns_search_add
+are never called
 then no searching will occur.
 .It
 If you do call
 .Fn evdns_resolv_conf_parse
 then don't pass
-.Va DNS_OPTION_SEARCH
+.Dv DNS_OPTION_SEARCH
 (or
-.Va DNS_OPTIONS_ALL,
+.Dv DNS_OPTIONS_ALL ,
 which implies it).
 .It
 When calling
-.Fn evdns_resolve,
+.Fn evdns_resolve ,
 pass the
-.Va DNS_QUERY_NO_SEARCH
+.Dv DNS_QUERY_NO_SEARCH
 flag.
 .El
 .Pp
@@ -160,89 +175,103 @@ 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.
+The ndots setting can either be set from a
+.Xr resolv.conf 5 ,
+or by calling
+.Fn 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
+.Bd -literal -offset indent
+Query: www
+Order: www.myhome.net, www.
+
+Query: www.abc
+Order: www.abc., www.abc.myhome.net
+.Ed
+.Sh API REFERENCE
 .Bl -tag -width 0123456
-.It Ft int Fn evdns_init
+.It Fn int evdns_init
 Initializes support for non-blocking name resolution by calling
 .Fn evdns_resolv_conf_parse .
-.It Ft int Fn evdns_nameserver_add "unsigned long int address"
+.It Fn int 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"
+.It Fn int 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"
+.It Fn int 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).
+The flags parameter should be 0, or
+.Dv DNS_QUERY_NO_SEARCH
+which disables searching for this query
+(see the definition 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
+The
+.Fa callback
+argument is a function which is called when
+this query completes and
+.Fa ptr
+is an argument which is passed
 to that callback function.
 .Pp
-Returns non-zero on error
-.It Ft void Fn evdns_search_clear
+Returns non-zero on error.
+.It Fn void evdns_search_clear
 Clears the list of search domains
-.It Ft void Fn evdns_search_add "const char *domain"
+.It Fn void 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"
+.It Fn void 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"
+.It Fn int 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
+This is useful for double checking whether calls to the various
 nameserver configuration functions have been successful.
-.It Ft int Fn evdns_clear_nameservers_and_suspend "void"
+.It Fn int 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"
+.Fn evdns_resume
+is called.
+.It Fn int evdns_resume "void"
 Re-attempt resolves left in limbo after an earlier call to
-evdns_clear_nameservers_and_suspend().
-.It Ft int Fn evdns_resolv_conf_parse "int flags" "const char *filename"
-Parse a resolv.conf like file from the given filename.
+.Fn evdns_clear_nameservers_and_suspend .
+.It Fn int 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.
+See the man page for
+.Xr resolv.conf 5
+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
+.Pp
+.Bl -tag -width "DNS_OPTION_NAMESERVERS" -offset indent -compact
+.It Dv DNS_OPTION_SEARCH
+Domain, search, and ndots options.
+.It Dv DNS_OPTION_NAMESERVERS
+Nameserver lines.
+.It Dv DNS_OPTION_MISC
+Timeout and attempts options.
+.It Dv DNS_OPTIONS_ALL
+All of the above.
 .El
 .Pp
-The following directives are not parsed from the file: lookup, sortlist.
+The following directives are not parsed from the file:
+lookup and sortlist.
 Additionally, the following
 .Dq options
-are ignored: debug, edns0, inet6, insecure1, insecure2.
+are ignored: debug, edns0, inet6, insecure1, and insecure2.
 .Pp
 Returns non-zero on error:
-.Bl -tag -width "0" -offset indent -compact -nested
+.Pp
+.Bl -tag -width "0XXX" -offset indent -compact
 .It 0
 no errors
 .It 1
@@ -257,23 +286,28 @@ out of memory
 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.
+.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.
 .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
+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 limits the number of concurrent requests
+so that the nameserver does not get flooded.
+Several algorithms require a full walk of the inflight
+queue so limiting 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
+try not to use it.
+After a while a probe is sent 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.
+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 ,
@@ -284,7 +318,7 @@ The
 API was developed by Adam Langley on top of the
 .Nm libevent
 API.
-The code was integrate into
+The code was integrated into
 .Nm Tor
 by Nick Mathewson and finally put into
 .Nm libevent