From 31a5cfd3b1cd0ca3f7a2871ecd21a8a5b8f7677c Mon Sep 17 00:00:00 2001 From: Azat Khuzhin Date: Wed, 16 Sep 2020 08:25:20 +0300 Subject: [PATCH] Remove man pages from repo (they can be generated via doxygen) The problem with this man pages are: - they are likely outdated - they don't have install target - and besides quality of man pages generated by doxygen not worse --- evdns.3 | 322 ----------------------------- event.3 | 624 -------------------------------------------------------- 2 files changed, 946 deletions(-) delete mode 100644 evdns.3 delete mode 100644 event.3 diff --git a/evdns.3 b/evdns.3 deleted file mode 100644 index 10414fa2..00000000 --- a/evdns.3 +++ /dev/null @@ -1,322 +0,0 @@ -.\" -.\" Copyright (c) 2006 Niels Provos -.\" 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 -.Fd #include -.Fd #include -.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. diff --git a/event.3 b/event.3 deleted file mode 100644 index 655a823e..00000000 --- a/event.3 +++ /dev/null @@ -1,624 +0,0 @@ -.\" $OpenBSD: event.3,v 1.4 2002/07/12 18:50:48 provos Exp $ -.\" -.\" Copyright (c) 2000 Artur Grabowski -.\" 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 August 8, 2000 -.Dt EVENT 3 -.Os -.Sh NAME -.Nm event_init , -.Nm event_dispatch , -.Nm event_loop , -.Nm event_loopexit , -.Nm event_loopbreak , -.Nm event_set , -.Nm event_base_dispatch , -.Nm event_base_loop , -.Nm event_base_loopexit , -.Nm event_base_loopbreak , -.Nm event_base_set , -.Nm event_base_free , -.Nm event_add , -.Nm event_del , -.Nm event_once , -.Nm event_base_once , -.Nm event_pending , -.Nm event_initialized , -.Nm event_priority_init , -.Nm event_priority_set , -.Nm evtimer_set , -.Nm evtimer_add , -.Nm evtimer_del , -.Nm evtimer_pending , -.Nm evtimer_initialized , -.Nm signal_set , -.Nm signal_add , -.Nm signal_del , -.Nm signal_pending , -.Nm signal_initialized , -.Nm bufferevent_new , -.Nm bufferevent_free , -.Nm bufferevent_write , -.Nm bufferevent_write_buffer , -.Nm bufferevent_read , -.Nm bufferevent_enable , -.Nm bufferevent_disable , -.Nm bufferevent_settimeout , -.Nm bufferevent_base_set , -.Nm evbuffer_new , -.Nm evbuffer_free , -.Nm evbuffer_add , -.Nm evbuffer_add_buffer , -.Nm evbuffer_add_printf , -.Nm evbuffer_add_vprintf , -.Nm evbuffer_drain , -.Nm evbuffer_write , -.Nm evbuffer_read , -.Nm evbuffer_find , -.Nm evbuffer_readline , -.Nm evhttp_new , -.Nm evhttp_bind_socket , -.Nm evhttp_free -.Nd execute a function when a specific event occurs -.Sh SYNOPSIS -.Fd #include -.Fd #include -.Ft "struct event_base *" -.Fn "event_init" "void" -.Ft int -.Fn "event_dispatch" "void" -.Ft int -.Fn "event_loop" "int flags" -.Ft int -.Fn "event_loopexit" "struct timeval *tv" -.Ft int -.Fn "event_loopbreak" "void" -.Ft void -.Fn "event_set" "struct event *ev" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" -.Ft int -.Fn "event_base_dispatch" "struct event_base *base" -.Ft int -.Fn "event_base_loop" "struct event_base *base" "int flags" -.Ft int -.Fn "event_base_loopexit" "struct event_base *base" "struct timeval *tv" -.Ft int -.Fn "event_base_loopbreak" "struct event_base *base" -.Ft int -.Fn "event_base_set" "struct event_base *base" "struct event *" -.Ft void -.Fn "event_base_free" "struct event_base *base" -.Ft int -.Fn "event_add" "struct event *ev" "struct timeval *tv" -.Ft int -.Fn "event_del" "struct event *ev" -.Ft int -.Fn "event_once" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv" -.Ft int -.Fn "event_base_once" "struct event_base *base" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv" -.Ft int -.Fn "event_pending" "struct event *ev" "short event" "struct timeval *tv" -.Ft int -.Fn "event_initialized" "struct event *ev" -.Ft int -.Fn "event_priority_init" "int npriorities" -.Ft int -.Fn "event_priority_set" "struct event *ev" "int priority" -.Ft void -.Fn "evtimer_set" "struct event *ev" "void (*fn)(int, short, void *)" "void *arg" -.Ft void -.Fn "evtimer_add" "struct event *ev" "struct timeval *" -.Ft void -.Fn "evtimer_del" "struct event *ev" -.Ft int -.Fn "evtimer_pending" "struct event *ev" "struct timeval *tv" -.Ft int -.Fn "evtimer_initialized" "struct event *ev" -.Ft void -.Fn "signal_set" "struct event *ev" "int signal" "void (*fn)(int, short, void *)" "void *arg" -.Ft void -.Fn "signal_add" "struct event *ev" "struct timeval *" -.Ft void -.Fn "signal_del" "struct event *ev" -.Ft int -.Fn "signal_pending" "struct event *ev" "struct timeval *tv" -.Ft int -.Fn "signal_initialized" "struct event *ev" -.Ft "struct bufferevent *" -.Fn "bufferevent_new" "int fd" "evbuffercb readcb" "evbuffercb writecb" "everrorcb" "void *cbarg" -.Ft void -.Fn "bufferevent_free" "struct bufferevent *bufev" -.Ft int -.Fn "bufferevent_write" "struct bufferevent *bufev" "void *data" "size_t size" -.Ft int -.Fn "bufferevent_write_buffer" "struct bufferevent *bufev" "struct evbuffer *buf" -.Ft size_t -.Fn "bufferevent_read" "struct bufferevent *bufev" "void *data" "size_t size" -.Ft int -.Fn "bufferevent_enable" "struct bufferevent *bufev" "short event" -.Ft int -.Fn "bufferevent_disable" "struct bufferevent *bufev" "short event" -.Ft void -.Fn "bufferevent_settimeout" "struct bufferevent *bufev" "int timeout_read" "int timeout_write" -.Ft int -.Fn "bufferevent_base_set" "struct event_base *base" "struct bufferevent *bufev" -.Ft "struct evbuffer *" -.Fn "evbuffer_new" "void" -.Ft void -.Fn "evbuffer_free" "struct evbuffer *buf" -.Ft int -.Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size" -.Ft int -.Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src" -.Ft int -.Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..." -.Ft int -.Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap" -.Ft void -.Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size" -.Ft int -.Fn "evbuffer_write" "struct evbuffer *buf" "int fd" -.Ft int -.Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size" -.Ft "unsigned char *" -.Fn "evbuffer_find" "struct evbuffer *buf" "const unsigned char *data" "size_t size" -.Ft "char *" -.Fn "evbuffer_readline" "struct evbuffer *buf" -.Ft "struct evhttp *" -.Fn "evhttp_new" "struct event_base *base" -.Ft int -.Fn "evhttp_bind_socket" "struct evhttp *http" "const char *address" "unsigned short port" -.Ft "void" -.Fn "evhttp_free" "struct evhttp *http" -.Ft int -.Fa (*event_sigcb)(void) ; -.Ft volatile sig_atomic_t -.Fa event_gotsig ; -.Sh DESCRIPTION -The -.Nm event -API provides a mechanism to execute a function when a specific event -on a file descriptor occurs or after a given time has passed. -.Pp -The -.Nm event -API needs to be initialized with -.Fn event_init -before it can be used. -.Pp -In order to process events, an application needs to call -.Fn event_dispatch . -This function only returns on error, and should replace the event core -of the application program. -.Pp -The function -.Fn event_set -prepares the event structure -.Fa ev -to be used in future calls to -.Fn event_add -and -.Fn event_del . -The event will be prepared to call the function specified by the -.Fa fn -argument with an -.Fa int -argument indicating the file descriptor, a -.Fa short -argument indicating the type of event, and a -.Fa void * -argument given in the -.Fa arg -argument. -The -.Fa fd -indicates the file descriptor that should be monitored for events. -The events can be either -.Va EV_READ , -.Va EV_WRITE , -or both, -indicating that an application can read or write from the file descriptor -respectively without blocking. -.Pp -The function -.Fa fn -will be called with the file descriptor that triggered the event and -the type of event which will be either -.Va EV_TIMEOUT , -.Va EV_SIGNAL , -.Va EV_READ , -or -.Va EV_WRITE . -Additionally, an event which has registered interest in more than one of the -preceeding events, via bitwise-OR to -.Fn event_set , -can provide its callback function with a bitwise-OR of more than one triggered -event. -The additional flag -.Va EV_PERSIST -makes an -.Fn event_add -persistent until -.Fn event_del -has been called. -.Pp -Once initialized, the -.Fa ev -structure can be used repeatedly with -.Fn event_add -and -.Fn event_del -and does not need to be reinitialized unless the function called and/or -the argument to it are to be changed. -However, when an -.Fa ev -structure has been added to libevent using -.Fn event_add -the structure must persist until the event occurs (assuming -.Fa EV_PERSIST -is not set) or is removed -using -.Fn event_del . -You may not reuse the same -.Fa ev -structure for multiple monitored descriptors; each descriptor -needs its own -.Fa ev . -.Pp -The function -.Fn event_add -schedules the execution of the -.Fa ev -event when the event specified in -.Fn event_set -occurs or in at least the time specified in the -.Fa tv . -If -.Fa tv -is -.Dv NULL , -no timeout occurs and the function will only be called -if a matching event occurs on the file descriptor. -The event in the -.Fa ev -argument must be already initialized by -.Fn event_set -and may not be used in calls to -.Fn event_set -until it has timed out or been removed with -.Fn event_del . -If the event in the -.Fa ev -argument already has a scheduled timeout, the old timeout will be -replaced by the new one. -.Pp -The function -.Fn event_del -will cancel the event in the argument -.Fa ev . -If the event has already executed or has never been added -the call will have no effect. -.Pp -The functions -.Fn evtimer_set , -.Fn evtimer_add , -.Fn evtimer_del , -.Fn evtimer_initialized , -and -.Fn evtimer_pending -are abbreviations for common situations where only a timeout is required. -The file descriptor passed will be \-1, and the event type will be -.Va EV_TIMEOUT . -.Pp -The functions -.Fn signal_set , -.Fn signal_add , -.Fn signal_del , -.Fn signal_initialized , -and -.Fn signal_pending -are abbreviations. -The event type will be a persistent -.Va EV_SIGNAL . -That means -.Fn signal_set -adds -.Va EV_PERSIST . -.Pp -In order to avoid races in signal handlers, the -.Nm event -API provides two variables: -.Va event_sigcb -and -.Va event_gotsig . -A signal handler -sets -.Va event_gotsig -to indicate that a signal has been received. -The application sets -.Va event_sigcb -to a callback function. -After the signal handler sets -.Va event_gotsig , -.Nm event_dispatch -will execute the callback function to process received signals. -The callback returns 1 when no events are registered any more. -It can return \-1 to indicate an error to the -.Nm event -library, causing -.Fn event_dispatch -to terminate with -.Va errno -set to -.Er EINTR . -.Pp -The function -.Fn event_once -is similar to -.Fn event_set . -However, it schedules a callback to be called exactly once and does not -require the caller to prepare an -.Fa event -structure. -This function supports -.Fa EV_TIMEOUT , -.Fa EV_READ , -and -.Fa EV_WRITE . -.Pp -The -.Fn event_pending -function can be used to check if the event specified by -.Fa event -is pending to run. -If -.Va EV_TIMEOUT -was specified and -.Fa tv -is not -.Dv NULL , -the expiration time of the event will be returned in -.Fa tv . -.Pp -The -.Fn event_initialized -macro can be used to check if an event has been initialized. -.Pp -The -.Nm event_loop -function provides an interface for single pass execution of pending -events. -The flags -.Va EVLOOP_ONCE -and -.Va EVLOOP_NONBLOCK -are recognized. -The -.Nm event_loopexit -function exits from the event loop. The next -.Fn event_loop -iteration after the -given timer expires will complete normally (handling all queued events) then -exit without blocking for events again. Subsequent invocations of -.Fn event_loop -will proceed normally. -The -.Nm event_loopbreak -function exits from the event loop immediately. -.Fn event_loop -will abort after the next event is completed; -.Fn event_loopbreak -is typically invoked from this event's callback. This behavior is analogous -to the "break;" statement. Subsequent invocations of -.Fn event_loop -will proceed normally. -.Pp -It is the responsibility of the caller to provide these functions with -pre-allocated event structures. -.Pp -.Sh EVENT PRIORITIES -By default -.Nm libevent -schedules all active events with the same priority. -However, sometimes it is desirable to process some events with a higher -priority than others. -For that reason, -.Nm libevent -supports strict priority queues. -Active events with a lower priority are always processed before events -with a higher priority. -.Pp -The number of different priorities can be set initially with the -.Fn event_priority_init -function. -This function should be called before the first call to -.Fn event_dispatch . -The -.Fn event_priority_set -function can be used to assign a priority to an event. -By default, -.Nm libevent -assigns the middle priority to all events unless their priority -is explicitly set. -.Sh THREAD SAFE EVENTS -.Nm Libevent -has experimental support for thread-safe events. -When initializing the library via -.Fn event_init , -an event base is returned. -This event base can be used in conjunction with calls to -.Fn event_base_set , -.Fn event_base_dispatch , -.Fn event_base_loop , -.Fn event_base_loopexit , -.Fn bufferevent_base_set -and -.Fn event_base_free . -.Fn event_base_set -should be called after preparing an event with -.Fn event_set , -as -.Fn event_set -assigns the provided event to the most recently created event base. -.Fn bufferevent_base_set -should be called after preparing a bufferevent with -.Fn bufferevent_new . -.Fn event_base_free -should be used to free memory associated with the event base -when it is no longer needed. -.Sh BUFFERED EVENTS -.Nm libevent -provides an abstraction on top of the regular event callbacks. -This abstraction is called a -.Va "buffered event" . -A buffered event provides input and output buffers that get filled -and drained automatically. -The user of a buffered event no longer deals directly with the IO, -but instead is reading from input and writing to output buffers. -.Pp -A new bufferevent is created by -.Fn bufferevent_new . -The parameter -.Fa fd -specifies the file descriptor from which data is read and written to. -This file descriptor is not allowed to be a -.Xr pipe 2 . -The next three parameters are callbacks. -The read and write callback have the following form: -.Ft void -.Fn "(*cb)" "struct bufferevent *bufev" "void *arg" . -The error callback has the following form: -.Ft void -.Fn "(*cb)" "struct bufferevent *bufev" "short what" "void *arg" . -The argument is specified by the fourth parameter -.Fa "cbarg" . -A -.Fa bufferevent struct -pointer is returned on success, NULL on error. -Both the read and the write callback may be NULL. -The error callback has to be always provided. -.Pp -Once initialized, the bufferevent structure can be used repeatedly with -bufferevent_enable() and bufferevent_disable(). -The flags parameter can be a combination of -.Va EV_READ -and -.Va EV_WRITE . -When read enabled the bufferevent will try to read from the file -descriptor and call the read callback. -The write callback is executed -whenever the output buffer is drained below the write low watermark, -which is -.Va 0 -by default. -.Pp -The -.Fn bufferevent_write -function can be used to write data to the file descriptor. -The data is appended to the output buffer and written to the descriptor -automatically as it becomes available for writing. -.Fn bufferevent_write -returns 0 on success or \-1 on failure. -The -.Fn bufferevent_read -function is used to read data from the input buffer, -returning the amount of data read. -.Pp -If multiple bases are in use, bufferevent_base_set() must be called before -enabling the bufferevent for the first time. -.Sh NON-BLOCKING HTTP SUPPORT -.Nm libevent -provides a very thin HTTP layer that can be used both to host an HTTP -server and also to make HTTP requests. -An HTTP server can be created by calling -.Fn evhttp_new . -It can be bound to any port and address with the -.Fn evhttp_bind_socket -function. -When the HTTP server is no longer used, it can be freed via -.Fn evhttp_free . -.Pp -To be notified of HTTP requests, a user needs to register callbacks with the -HTTP server. -This can be done by calling -.Fn evhttp_set_cb . -The second argument is the URI for which a callback is being registered. -The corresponding callback will receive an -.Va struct evhttp_request -object that contains all information about the request. -.Pp -This section does not document all the possible function calls; please -check -.Va event.h -for the public interfaces. -.Sh ADDITIONAL NOTES -It is possible to disable support for -.Va epoll , kqueue , devpoll , poll -or -.Va select -by setting the environment variable -.Va EVENT_NOEPOLL , EVENT_NOKQUEUE , EVENT_NODEVPOLL , EVENT_NOPOLL -or -.Va EVENT_NOSELECT , -respectively. -By setting the environment variable -.Va EVENT_SHOW_METHOD , -.Nm libevent -displays the kernel notification method that it uses. -.Sh RETURN VALUES -Upon successful completion -.Fn event_add -and -.Fn event_del -return 0. -Otherwise, \-1 is returned and the global variable errno is -set to indicate the error. -.Sh SEE ALSO -.Xr kqueue 2 , -.Xr poll 2 , -.Xr select 2 , -.Xr evdns 3 , -.Xr timeout 9 -.Sh HISTORY -The -.Nm event -API manpage is based on the -.Xr timeout 9 -manpage by Artur Grabowski. -The port of -.Nm libevent -to Windows is due to Michael A. Davis. -Support for real-time signals is due to Taral. -.Sh AUTHORS -The -.Nm event -library was written by Niels Provos. -.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.