--- libevent-1.3e/event.3.orig	Wed Apr 27 12:03:35 2011

+++ libevent-1.3e/event.3	Wed Apr 27 12:03:55 2011

@@ -26,567 +26,453 @@

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

-.Nm event_base_dispatch ,

-.Nm event_base_loop ,

-.Nm event_base_loopexit ,

-.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_start ,

-.Nm evhttp_free

-.Nd execute a function when a specific event occurs

-.Sh SYNOPSIS

-.Fd #include <sys/time.h>

-.Fd #include <event.h>

-.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 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_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 "u_char *"

-.Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size"

-.Ft "char *"

-.Fn "evbuffer_readline" "struct evbuffer *buf"

-.Ft "struct evhttp *"

-.Fn "evhttp_start" "const char *address" "u_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

+.TH EVENT 3 "8 August 2000" "libevent 1.3e" "libevent Manual"

+.SH NAME

+event_init, event_dispatch, event_loop, event_loopexit, event_set, event_base_dispatch, event_base_loop, event_base_loopexit, event_base_set, event_base_free, event_add, event_del, event_once, event_base_once, event_pending, event_initialized, event_priority_init, event_priority_set, evtimer_set, evtimer_add, evtimer_del, evtimer_pending, evtimer_initialized, signal_set, signal_add, signal_del, signal_pending, signal_initialized, bufferevent_new, bufferevent_free, bufferevent_write, bufferevent_write_buffer, bufferevent_read, bufferevent_enable, bufferevent_disable, bufferevent_settimeout, bufferevent_base_set, evbuffer_new, evbuffer_free, evbuffer_add, evbuffer_add_buffer, evbuffer_add_printf, evbuffer_add_vprintf, evbuffer_drain, evbuffer_write, evbuffer_read, evbuffer_find, evbuffer_readline

+.SH LIBRARY

+The libevent library (libevent, -levent)

+.br

+.SH SYNOPSIS

+\fB#include <sys/time.h>\fP

+.br

+\fB#include <event.h>\fP

+.sp

+\fBstruct event_base* \fBevent_init\fR\fR(\fBvoid\fP\fR);

+.br

+\fBint \fBevent_dispatch\fR\fR(\fBvoid\fP\fR);

+.br

+\fBint \fBevent_loop\fR\fR(\fBint \fIflags\fP\fR);

+.br

+.BI "int event_loopexit(struct timeval* " tv ");"

+.br

+\fBvoid \fBevent_set\fR\fR(\fBstruct event* \fIev\fP\fR, \fBint \fIfd \fP\fR, \fBshort \fIevent\fP\fR, \fBvoid \fI(*fn)(int, short, void *)\fP\fR, \fBvoid* \fIarg\fP\fR);

+.br

+\fBint \fBevent_base_dispatch\fR\fR(\fBstruct event_base* \fIbase\fP\fR);

+.br

+\fBint \fBevent_base_loop\fR\fR(\fBstruct event_base* \fIbase\fP\fR, \fBint \fIflags\fP\fR);

+.br

+\fBint \fBevent_base_loopexit\fR\fR(struct event_base* \fIbase\fP\fR, \fBstruct timeval* \fItv\fP\fR);

+.br

+\fBint \fBevent_base_set\fR\fR(struct event_base* \fIbase\fP\fR, \fBstruct event* \fIev\fP\fR);

+.br

+\fBvoid \fBevent_base_free\fR\fR(struct event_base* \fIbase\fP\fR);

+.br

+\fBint \fBevent_add\fR\fR(struct event* \fIev\fP\fR, \fBstruct timeval* \fItv\fP\fR);

+.br

+.\fBint \fBevent_del\fR\fR(struct event* \fIev\fP\fR);

+.br

+\fBint \fBevent_once\fR\fR(int \fIfd\fP\fR, \fBshort \fIevent\fP\fR, \fBvoid \fI(*fn)(int, short, void*)\fB\fR, \fBstruct timeval* \fItv\fP\fR);

+.br

+\fBint \fBevent_base_once\fR\fR(struct event_base* \fIbase\fP\fR, \fBint \fIfd\fB\fR, \fBshort \fIevent\fB\fR, \fBvoid \fI(*fn)(int, short, void*)\fB\fR, \fBvoid* \fIarg\fB\fR, \fBstruct timeval* \fItv\fP\fR);

+.br

+\fBint \fBevent_pending\fR\fR(struct event* \fIev\fP\fR, \fBshort \fIevent\fB\fR, \fBstruct timeval* \fItv\fP\fR);

+.br

+\fBint \fBevent_initialized\fR\fR(struct event* \fIev\fP\fR);

+.br

+\fBint \fBevent_priority_init\fR\fR (int \fInpriorities\fP\fR);

+.br

+\fBint \fBevent_priority_set\fR\fR (struct event* \fIev\fP\fR, \fBint \fIpriority\fP\fR);

+.br

+\fBvoid \fBevtimer_set\fR\fR (struct event* \fIev\fP\fR, \fBvoid \fI(*fn)(int, short, void*)\fB\fR, \fBvoid* \fIarg\fP\fR);

+.br

+\fBvoid \fBevtimer_add\fR\fR (struct event* \fIev\fP\fR, \fBstruct timeval* \fItv\fP\fR);

+.br

+\fBvoid \fBevtimer_del\fR\fR (struct event* \fIev\fP\fR);

+.br

+\fBint \fBevtimer_pending\fR\fR (struct event* \fIev\fP\fR, \fBstruct timeval* \fItv\fP\fR);

+.br

+\fBint \fBevtimer_initialized\fR\fR(struct event* \fIev\fP\fR);

+.br

+\fBvoid \fBsignal_set\fR\fR (struct event* \fIev\fP\fR, \fBint \fIsignal\fP\fR, \fBvoid \fI(*fn)(int, short, void*)\fP\fR, \fBvoid* \fIarg\fP\fR);

+.br

+\fBvoid \fBsignal_add\fR\fR (struct event* \fIev\fP\fR, \fBstruct timeval* \fItv\fP\fR);

+.br

+\fBvoid \fBsignal_del\fR\fR (struct event* \fIev\fP\fR);

+.br

+\fBint \fBsignal_pending\fR\fR(struct event* \fIev\fP\fR, \fBstruct timeval* \fItv\fP\fR);

+.br

+\fBint \fBsignal_initialized\fR\fR(struct event* \fIev\fP\fR);

+.br

+\fBstruct bufferevent* \fB"bufferevent_new\fR\fR(int \fIfd\fP\fR, \fBevbuffercb \fIreadcb\fP\fR, \fBevbuffercb \fIwritecb\fP\fR, \fBeverrorcb \fIerrorcb\fP\fR, \fBvoid* \fIcbarg\fP\fR);

+.br

+\fBvoid \fBbufferevent_free\fR\fR(struct bufferevent* \fIbufev\fP\fR);

+.br

+\fBint \fBbufferevent_write\fR\fR(struct bufferevent* \fIbufev\fP\fR, \fBvoid* \fIdata\fP\fR, \fBsize_t \fIsize\fP\fR);

+.br

+\fBint \fBbufferevent_write_buffer\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBstruct evbuffer* \fIbuf\fP\fR);

+.br

+\fBsize_t \fBbufferevent_read\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBvoid* \fIdata\fP\fR, \fBsize_t \fIsize\fP\fR);

+.br

+\fBint \fBbufferevent_enable\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBshort \fIevent\fP\fR);

+.br

+\fBint \fBbufferevent_disable\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBshort \fIeven\fP\fR);

+.br

+\fBvoid \fBbufferevent_settimeout\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBint \fItimeout_read\fP\fR, \fBint \fItimeout_write\fP\fR);

+.br

+\fBint \fBbufferevent_base_set\fR\fR(\fBstruct event_base* \fIbase\fP\fR, \fBstruct bufferevent* \fIbufev\fP\fR);

+.br

+\fBstruct evbuffer* \fBevbuffer_new (\fBvoid\fP\fR);

+.br

+\fBvoid \fBvbuffer_free\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR);

+.br

+\fBint \fBevbuffer_add\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBconst void* \fIdata\fP\fR, \fBsize_t \fIsize\fP\fR);

+.br

+\fBint \fBevbuffer_add_buffer\fR\fR(\fBstruct evbuffer* \fIdst\fP\fR, \fBstruct evbuffer* \fIsrc\fP\fR);

+.br

+\fBint \fBevbuffer_add_printf\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBconst char* \fIfmt\fP\fR, \fB...\fP\fR);

+.br

+\fBint \fBevbuffer_add_vprintf\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBconst char* \fIfmt\fP\fR, \fBva_list \fIap\fP\fR);

+.br

+\fBvoid \fBevbuffer_drain\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBsize_t \fIsize\fP\fR);

+.br

+\fBint \fBevbuffer_write\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBint \fIfd\fP\fR);

+.br

+\fBint \fBevbuffer_read\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBint \fIfd\fP\fR, \fBint \fIsize\fP\fR);

+.br

+\fBu_char* \fBevbuffer_find\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBconst u_char* \fIdata\fP\fR, \fBsize_t \fIsize\fP\fR);

+.br

+\fBchar* \fBevbuffer_readline\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR);

+.br

+\fBint \fI(*event_sigcb)\fP\fR\fI(void)\fP\fR;

+.br

+\fBvolatile sig_atomic_t \fR\fRevent_gotsig\fP\fR;

+.br

+.SH DESCRIPTION

 The

-.Nm event

+\fIevent\fP\fR

 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

+.PP

 The

-.Nm event

+\fIevent\fP\fR

 API needs to be initialized with

-.Fn event_init

+\fBevent_init\fR

 before it can be used.

-.Pp

+.PP

 In order to process events, an application needs to call

-.Fn event_dispatch .

+\fIevent_dispatch\fP\fR .

 This function only returns on error, and should replace the event core

 of the application program.

-.Pp

+.PP

 In order to avoid races in signal handlers, the

-.Nm event

+\fIevent\fP\fR

 API provides two variables:

-.Va event_sigcb

+\fIevent_sigcb\fP\fR

 and

-.Va event_gotsig .

+\fIevent_gotsig\fP\fR.

 A signal handler

 sets

-.Va event_gotsig

+\fIevent_gotsig\fP\fR

 to indicate that a signal has been received.

 The application sets

-.Va event_sigcb

+\fIevent_sigcb\fP\fR

 to a callback function.

 After the signal handler sets

-.Va event_gotsig ,

-.Nm event_dispatch

+\fIevent_gotsig\fP\fR,

+\fBevent_dispatch()\fP\fR

 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

+\fIevent\fP\fR

 library, causing

-.Fn event_dispatch

+\fBevent_dispatch\fP\fR

 to terminate with

-.Va errno

-set to

-.Er EINTR .

-.Pp

+\fIerrno\fP\fR

+set to EINTR.

+.PO

 The

-.Nm event_loop

+\fIevent_loop\fP\fR

 function provides an interface for single pass execution of pending

 events.

 The flags

-.Va EVLOOP_ONCE

-and

-.Va EVLOOP_NONBLOCK

-are recognized.

+EVLOOP_ONCE and EVLOOP_NONBLOCK are recognized.

 The

-.Nm event_loopexit

+\fIevent_loopexit\fP\fR

 function allows the loop to be terminated after some amount of time

 has passed.

 The parameter indicates the time after which the loop should terminate.

-.Pp

+.PP

 It is the responsibility of the caller to provide these functions with

 pre-allocated event structures.

-.Pp

+.PP

 The function

-.Fn event_set

+\fBevent_set\fP\fR

 prepares the event structure

-.Fa ev

+\fIev\fP\fR

 to be used in future calls to

-.Fn event_add

+\fBevent_add\fP\fR

 and

-.Fn event_del .

+\fBevent_del\fP\fR .

 The event will be prepared to call the function specified by the

-.Fa fn

+\fIfn\fP\fR

 argument with an

-.Fa int

+\fIint\fP\fR

 argument indicating the file descriptor, a

-.Fa short

+\fIshort\fP\fR

 argument indicating the type of event, and a

-.Fa void *

+\fIvoid*\fP\fR

 argument given in the

-.Fa arg

+\fIarg\fP\fR

 argument.

-The

-.Fa fd

+The \fIfd\fP\fR

 indicates the file descriptor that should be monitored for events.

-The events can be either

-.Va EV_READ ,

-.Va EV_WRITE ,

-or both,

+The events can be either EV_READ, EV_WRITE , or both,

 indicating that an application can read or write from the file descriptor

 respectively without blocking.

-.Pp

+.PP

 The function

-.Fa fn

+\fIfn\fP\fR

 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 .

-The additional flag

-.Va EV_PERSIST

-makes an

-.Fn event_add

-persistent until

-.Fn event_del

+the type of event which will be either EV_TIMEOUT, EV_SIGNAL,

+EV_READ, or EV_WRITE.  The additional flag EV_PERSIST makes an

+\fIevent_add\fP\fR persistent until

+\fIevent_del\fP\fR

 has been called.

-.Pp

+.PP

 Once initialized, the

-.Fa ev

+\fIev\fP\fR

 structure can be used repeatedly with

-.Fn event_add

+\fIevent_add\fP\fR

 and

-.Fn event_del

+\fIevent_del\fP\fR

 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

+\fIev\fP\fR

 structure has been added to libevent using

-.Fn event_add

+\fIevent_add\fP\fR

 the structure must persist until the event occurs (assuming

-.Fa EV_PERSIST

-is not set) or is removed

-using

-.Fn event_del .

+EV_PERSIST is not set) or is removed using

+\fIevent_del\fP\fR .

 You may not reuse the same

-.Fa ev

+\fIev\fP\fR

 structure for multiple monitored descriptors; each descriptor

-needs its own

-.Fa ev .

-.Pp

+needs its own \fIev\fP\fR .

+.PP

 The function

-.Fn event_add

+\fIevent_add\fP\fR

 schedules the execution of the

-.Fa ev

+\fIev\fP\fR

 event when the event specified in

-.Fn event_set

+\fBevent_set\fP\fR

 occurs or in at least the time specified in the

-.Fa tv .

+\fItv\fP\fR .

 If

-.Fa tv

-is

-.Dv NULL ,

-no timeout occurs and the function will only be called

+\fItv\fP\fR

+is 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

+\fIev\fP\fR

 argument must be already initialized by

-.Fn event_set

+\fIevent_set\fP\fR

 and may not be used in calls to

-.Fn event_set

+\fIevent_set\fP\fR

 until it has timed out or been removed with

-.Fn event_del .

+\fIevent_del\fP\fR .

 If the event in the

-.Fa ev

+\fIev\fP\fR

 argument already has a scheduled timeout, the old timeout will be

 replaced by the new one.

-.Pp

+.PP

 The function

-.Fn event_del

+\fIevent_del\fP\fR

 will cancel the event in the argument

-.Fa ev .

+\fIev\fP\fR .

 If the event has already executed or has never been added

 the call will have no effect.

-.Pp

+.PP

 The function

-.Fn event_once

+\fIevent_once\fP\fR

 is similar to

-.Fn event_set .

+\fIevent_set\fP\fR.

 However, it schedules a callback to be called exactly once and does not

 require the caller to prepare an

-.Fa event

+\fIevent\fP\fR

 structure.

-This function supports

-.Fa EV_TIMEOUT ,

-.Fa EV_READ ,

-and

-.Fa EV_WRITE .

-.Pp