1
.\" $OpenBSD: event.3,v 1.4 2002/07/12 18:50:48 provos Exp $
3
.\" Copyright (c) 2000 Artur Grabowski <art@openbsd.org>
4
.\" All rights reserved.
6
.\" Redistribution and use in source and binary forms, with or without
7
.\" modification, are permitted provided that the following conditions
10
.\" 1. Redistributions of source code must retain the above copyright
11
.\" notice, this list of conditions and the following disclaimer.
12
.\" 2. Redistributions in binary form must reproduce the above copyright
13
.\" notice, this list of conditions and the following disclaimer in the
14
.\" documentation and/or other materials provided with the distribution.
15
.\" 3. The name of the author may not be used to endorse or promote products
16
.\" derived from this software without specific prior written permission.
18
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
19
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
20
.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
21
.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22
.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
23
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
24
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
25
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
26
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
27
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38
.Nm event_base_dispatch ,
40
.Nm event_base_loopexit ,
48
.Nm event_initialized ,
49
.Nm event_priority_init ,
50
.Nm event_priority_set ,
55
.Nm evtimer_initialized ,
60
.Nm signal_initialized ,
62
.Nm bufferevent_free ,
63
.Nm bufferevent_write ,
64
.Nm bufferevent_write_buffer ,
65
.Nm bufferevent_read ,
66
.Nm bufferevent_enable ,
67
.Nm bufferevent_disable ,
68
.Nm bufferevent_settimeout ,
69
.Nm bufferevent_base_set ,
73
.Nm evbuffer_add_buffer ,
74
.Nm evbuffer_add_printf ,
75
.Nm evbuffer_add_vprintf ,
80
.Nm evbuffer_readline ,
82
.Nm evhttp_bind_socket ,
84
.Nd execute a function when a specific event occurs
86
.Fd #include <sys/time.h>
87
.Fd #include <event.h>
88
.Ft "struct event_base *"
89
.Fn "event_init" "void"
91
.Fn "event_dispatch" "void"
93
.Fn "event_loop" "int flags"
95
.Fn "event_loopexit" "struct timeval *tv"
97
.Fn "event_set" "struct event *ev" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg"
99
.Fn "event_base_dispatch" "struct event_base *base"
101
.Fn "event_base_loop" "struct event_base *base" "int flags"
103
.Fn "event_base_loopexit" "struct event_base *base" "struct timeval *tv"
105
.Fn "event_base_set" "struct event_base *base" "struct event *"
107
.Fn "event_base_free" "struct event_base *base"
109
.Fn "event_add" "struct event *ev" "struct timeval *tv"
111
.Fn "event_del" "struct event *ev"
113
.Fn "event_once" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv"
115
.Fn "event_base_once" "struct event_base *base" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv"
117
.Fn "event_pending" "struct event *ev" "short event" "struct timeval *tv"
119
.Fn "event_initialized" "struct event *ev"
121
.Fn "event_priority_init" "int npriorities"
123
.Fn "event_priority_set" "struct event *ev" "int priority"
125
.Fn "evtimer_set" "struct event *ev" "void (*fn)(int, short, void *)" "void *arg"
127
.Fn "evtimer_add" "struct event *ev" "struct timeval *"
129
.Fn "evtimer_del" "struct event *ev"
131
.Fn "evtimer_pending" "struct event *ev" "struct timeval *tv"
133
.Fn "evtimer_initialized" "struct event *ev"
135
.Fn "signal_set" "struct event *ev" "int signal" "void (*fn)(int, short, void *)" "void *arg"
137
.Fn "signal_add" "struct event *ev" "struct timeval *"
139
.Fn "signal_del" "struct event *ev"
141
.Fn "signal_pending" "struct event *ev" "struct timeval *tv"
143
.Fn "signal_initialized" "struct event *ev"
144
.Ft "struct bufferevent *"
145
.Fn "bufferevent_new" "int fd" "evbuffercb readcb" "evbuffercb writecb" "everrorcb" "void *cbarg"
147
.Fn "bufferevent_free" "struct bufferevent *bufev"
149
.Fn "bufferevent_write" "struct bufferevent *bufev" "void *data" "size_t size"
151
.Fn "bufferevent_write_buffer" "struct bufferevent *bufev" "struct evbuffer *buf"
153
.Fn "bufferevent_read" "struct bufferevent *bufev" "void *data" "size_t size"
155
.Fn "bufferevent_enable" "struct bufferevent *bufev" "short event"
157
.Fn "bufferevent_disable" "struct bufferevent *bufev" "short event"
159
.Fn "bufferevent_settimeout" "struct bufferevent *bufev" "int timeout_read" "int timeout_write"
161
.Fn "bufferevent_base_set" "struct event_base *base" "struct bufferevent *bufev"
162
.Ft "struct evbuffer *"
163
.Fn "evbuffer_new" "void"
165
.Fn "evbuffer_free" "struct evbuffer *buf"
167
.Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size"
169
.Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src"
171
.Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..."
173
.Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap"
175
.Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size"
177
.Fn "evbuffer_write" "struct evbuffer *buf" "int fd"
179
.Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size"
181
.Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size"
183
.Fn "evbuffer_readline" "struct evbuffer *buf"
184
.Ft "struct evhttp *"
187
.Fn "evhttp_bind_socket" "struct evhttp *http" "const char *address" "u_short port"
189
.Fn "evhttp_free" "struct evhttp *http"
191
.Fa (*event_sigcb)(void) ;
192
.Ft volatile sig_atomic_t
197
API provides a mechanism to execute a function when a specific event
198
on a file descriptor occurs or after a given time has passed.
202
API needs to be initialized with
204
before it can be used.
206
In order to process events, an application needs to call
208
This function only returns on error, and should replace the event core
209
of the application program.
213
prepares the event structure
215
to be used in future calls to
219
The event will be prepared to call the function specified by the
223
argument indicating the file descriptor, a
225
argument indicating the type of event, and a
227
argument given in the
232
indicates the file descriptor that should be monitored for events.
233
The events can be either
237
indicating that an application can read or write from the file descriptor
238
respectively without blocking.
242
will be called with the file descriptor that triggered the event and
243
the type of event which will be either
249
Additionally, an event which has registered interest in more than one of the
250
preceeding events, via bitwise-OR to
252
can provide its callback function with a bitwise-OR of more than one triggered
262
Once initialized, the
264
structure can be used repeatedly with
268
and does not need to be reinitialized unless the function called and/or
269
the argument to it are to be changed.
272
structure has been added to libevent using
274
the structure must persist until the event occurs (assuming
276
is not set) or is removed
279
You may not reuse the same
281
structure for multiple monitored descriptors; each descriptor
287
schedules the execution of the
289
event when the event specified in
291
occurs or in at least the time specified in the
297
no timeout occurs and the function will only be called
298
if a matching event occurs on the file descriptor.
301
argument must be already initialized by
303
and may not be used in calls to
305
until it has timed out or been removed with
309
argument already has a scheduled timeout, the old timeout will be
310
replaced by the new one.
314
will cancel the event in the argument
316
If the event has already executed or has never been added
317
the call will have no effect.
323
.Fn evtimer_initialized ,
326
are abbreviations for common situations where only a timeout is required.
327
The file descriptor passed will be \-1, and the event type will be
334
.Fn signal_initialized ,
338
The event type will be a persistent
345
In order to avoid races in signal handlers, the
347
API provides two variables:
354
to indicate that a signal has been received.
357
to a callback function.
358
After the signal handler sets
361
will execute the callback function to process received signals.
362
The callback returns 1 when no events are registered any more.
363
It can return \-1 to indicate an error to the
376
However, it schedules a callback to be called exactly once and does not
377
require the caller to prepare an
380
This function supports
388
function can be used to check if the event specified by
397
the expiration time of the event will be returned in
401
.Fn event_initialized
402
macro can be used to check if an event has been initialized.
406
function provides an interface for single pass execution of pending
415
function allows the loop to be terminated after some amount of time
417
The parameter indicates the time after which the loop should terminate.
419
It is the responsibility of the caller to provide these functions with
420
pre-allocated event structures.
425
schedules all active events with the same priority.
426
However, sometimes it is desirable to process some events with a higher
427
priority than others.
430
supports strict priority queues.
431
Active events with a lower priority are always processed before events
432
with a higher priority.
434
The number of different priorities can be set initially with the
435
.Fn event_priority_init
437
This function should be called before the first call to
440
.Fn event_priority_set
441
function can be used to assign a priority to an event.
444
assigns the middle priority to all events unless their priority
446
.Sh THREAD SAFE EVENTS
448
has experimental support for thread-safe events.
449
When initializing the library via
451
an event base is returned.
452
This event base can be used in conjunction with calls to
454
.Fn event_base_dispatch ,
455
.Fn event_base_loop ,
456
.Fn event_base_loopexit ,
457
.Fn bufferevent_base_set
459
.Fn event_base_free .
461
should be called after preparing an event with
465
assigns the provided event to the most recently created event base.
466
.Fn bufferevent_base_set
467
should be called after preparing a bufferevent with
468
.Fn bufferevent_new .
470
should be used to free memory associated with the event base
471
when it is no longer needed.
474
provides an abstraction on top of the regular event callbacks.
475
This abstraction is called a
476
.Va "buffered event" .
477
A buffered event provides input and output buffers that get filled
478
and drained automatically.
479
The user of a buffered event no longer deals directly with the IO,
480
but instead is reading from input and writing to output buffers.
482
A new bufferevent is created by
483
.Fn bufferevent_new .
486
specifies the file descriptor from which data is read and written to.
487
This file descriptor is not allowed to be a
489
The next three parameters are callbacks.
490
The read and write callback have the following form:
492
.Fn "(*cb)" "struct bufferevent *bufev" "void *arg" .
493
The error callback has the following form:
495
.Fn "(*cb)" "struct bufferevent *bufev" "short what" "void *arg" .
496
The argument is specified by the fourth parameter
499
.Fa bufferevent struct
500
pointer is returned on success, NULL on error.
501
Both the read and the write callback may be NULL.
502
The error callback has to be always provided.
504
Once initialized, the bufferevent structure can be used repeatedly with
505
bufferevent_enable() and bufferevent_disable().
506
The flags parameter can be a combination of
510
When read enabled the bufferevent will try to read from the file
511
descriptor and call the read callback.
512
The write callback is executed
513
whenever the output buffer is drained below the write low watermark,
519
.Fn bufferevent_write
520
function can be used to write data to the file descriptor.
521
The data is appended to the output buffer and written to the descriptor
522
automatically as it becomes available for writing.
523
.Fn bufferevent_write
524
returns 0 on success or \-1 on failure.
527
function is used to read data from the input buffer,
528
returning the amount of data read.
530
If multiple bases are in use, bufferevent_base_set() must be called before
531
enabling the bufferevent for the first time.
532
.Sh NON-BLOCKING HTTP SUPPORT
534
provides a very thin HTTP layer that can be used both to host an HTTP
535
server and also to make HTTP requests.
536
An HTTP server can be created by calling
538
It can be bound to any port and address with the
539
.Fn evhttp_bind_socket
541
When the HTTP server is no longer used, it can be freed via
544
To be notified of HTTP requests, a user needs to register callbacks with the
546
This can be done by calling
548
The second argument is the URI for which a callback is being registered.
549
The corresponding callback will receive an
550
.Va struct evhttp_request
551
object that contains all information about the request.
553
This section does not document all the possible function calls; please
556
for the public interfaces.
558
It is possible to disable support for
559
.Va epoll , kqueue , devpoll , poll
562
by setting the environment variable
563
.Va EVENT_NOEPOLL , EVENT_NOKQUEUE , EVENT_NODEVPOLL , EVENT_NOPOLL
567
By setting the environment variable
568
.Va EVENT_SHOW_METHOD ,
570
displays the kernel notification method that it uses.
572
Upon successful completion
577
Otherwise, \-1 is returned and the global variable errno is
578
set to indicate the error.
588
API manpage is based on the
590
manpage by Artur Grabowski.
593
to Windows is due to Michael A. Davis.
594
Support for real-time signals is due to Taral.
598
library was written by Niels Provos.
600
This documentation is neither complete nor authoritative.
601
If you are in doubt about the usage of this API then
602
check the source code to find out how it works, write
603
up the missing piece of documentation and send it to
604
me for inclusion in this man page.
added
removed
third-party/libevent/event.3
