--- libevent-1.4.14b-stable/event.3	po lis 21 06:43:10 2011

+++ libevent-1.4.14b-stable/event.3	po lis 21 09:31:12 2011

@@ -26,527 +26,528 @@

 .\" 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 <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 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 "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_new" "struct event_base *base"

-.Ft int

-.Fn "evhttp_bind_socket" "struct evhttp *http" "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 "21 November 2011" "libevent 1.4.14b" "libevent Manual"

+.SH NAME

+event_init,

+event_dispatch,

+event_loop,

+event_loopexit,

+event_loopbreak,

+event_set,

+event_base_dispatch,

+event_base_loop,

+event_base_loopexit,

+event_base_loopbreak,

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

+evhttp_new,

+evhttp_bind_socket,

+evhttp_free

+\- execute a function when a specific event occurs

+.SH LIBRARY

+The libevent library (libevent, -levent)

+.br

+.SH SYNOPSIS

+.LP

+.nf

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

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

+

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

+

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

+

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

+

+\fBint \fBevent_loopexit\fR\fR(\fBstruct timeval* \fItv\fP\fR);

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

+\fBstruct bufferevent* \fBbufferevent_new\fR\fR(\fBint \fIfd\fP\fR, \fBevbuffercb \fIreadcb\fP\fR, \fBevbuffercb \fIwritecb\fP\fR, \fBeverrorcb \fIerrorcb\fP\fR, \fBvoid* \fIcbarg\fP\fR);

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

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

+

+\fBstruct evhttp * \fBevhttp_new\fR\fR(\fBstruct event_base* \fIbase\fP\fR);

+

+\fBint \fBevhttp_bind_socket\fR\fR(\fBstruct evhttp* \fIhttp\fP\fR, \fBconst char* \fIaddress\fP\fR, \fBu_short \fIport\fP\fR);

+

+\fBvoid \fBevhttp_free\fR\fR(\fBstruct evhttp* \fIhttp\fP\fR);

+

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

+

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

+.fi

+

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

+\fBevent_dispatch\fP\fR.

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

 of the application program.

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

+EV_TIMEOUT,

+EV_SIGNAL,

+EV_READ,

 or

-.Va EV_WRITE .

+EV_WRITE.

 Additionally, an event which has registered interest in more than one of the

 preceeding events, via bitwise-OR to

-.Fn event_set ,

+\fBevent_set\fP\fR,

 can provide its callback function with a bitwise-OR of more than one triggered

 event.

 The additional flag

-.Va EV_PERSIST

+EV_PERSIST

 makes an

-.Fn event_add

+\fBevent_add\fP\fR

 persistent until

-.Fn event_del

+\fBevent_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

+\fBevent_add\fP\fR

 and

-.Fn event_del

+\fBevent_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

+\fBevent_add\fP\fR

 the structure must persist until the event occurs (assuming

-.Fa EV_PERSIST

+EV_PERSIST

 is not set) or is removed

 using

-.Fn event_del .

+\fBevent_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

+\fIev\fP\fR.

+.PP

 The function

-.Fn event_add

+\fBevent_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

+\fItv\fP\fR

 is

-.Dv NULL ,

+\fINULL\fP\fR,

 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