|
1 --- libevent-1.3e/event.3.orig Wed Apr 27 12:03:35 2011 |
|
2 +++ libevent-1.3e/event.3 Wed Apr 27 12:03:55 2011 |
|
3 @@ -26,567 +26,453 @@ |
|
4 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF |
|
5 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
6 .\" |
|
7 -.Dd August 8, 2000 |
|
8 -.Dt EVENT 3 |
|
9 -.Os |
|
10 -.Sh NAME |
|
11 -.Nm event_init , |
|
12 -.Nm event_dispatch , |
|
13 -.Nm event_loop , |
|
14 -.Nm event_loopexit , |
|
15 -.Nm event_set , |
|
16 -.Nm event_base_dispatch , |
|
17 -.Nm event_base_loop , |
|
18 -.Nm event_base_loopexit , |
|
19 -.Nm event_base_set , |
|
20 -.Nm event_base_free , |
|
21 -.Nm event_add , |
|
22 -.Nm event_del , |
|
23 -.Nm event_once , |
|
24 -.Nm event_base_once , |
|
25 -.Nm event_pending , |
|
26 -.Nm event_initialized , |
|
27 -.Nm event_priority_init , |
|
28 -.Nm event_priority_set , |
|
29 -.Nm evtimer_set , |
|
30 -.Nm evtimer_add , |
|
31 -.Nm evtimer_del , |
|
32 -.Nm evtimer_pending , |
|
33 -.Nm evtimer_initialized , |
|
34 -.Nm signal_set , |
|
35 -.Nm signal_add , |
|
36 -.Nm signal_del , |
|
37 -.Nm signal_pending , |
|
38 -.Nm signal_initialized , |
|
39 -.Nm bufferevent_new , |
|
40 -.Nm bufferevent_free , |
|
41 -.Nm bufferevent_write , |
|
42 -.Nm bufferevent_write_buffer , |
|
43 -.Nm bufferevent_read , |
|
44 -.Nm bufferevent_enable , |
|
45 -.Nm bufferevent_disable , |
|
46 -.Nm bufferevent_settimeout , |
|
47 -.Nm bufferevent_base_set , |
|
48 -.Nm evbuffer_new , |
|
49 -.Nm evbuffer_free , |
|
50 -.Nm evbuffer_add , |
|
51 -.Nm evbuffer_add_buffer , |
|
52 -.Nm evbuffer_add_printf , |
|
53 -.Nm evbuffer_add_vprintf , |
|
54 -.Nm evbuffer_drain , |
|
55 -.Nm evbuffer_write , |
|
56 -.Nm evbuffer_read , |
|
57 -.Nm evbuffer_find , |
|
58 -.Nm evbuffer_readline , |
|
59 -.Nm evhttp_start , |
|
60 -.Nm evhttp_free |
|
61 -.Nd execute a function when a specific event occurs |
|
62 -.Sh SYNOPSIS |
|
63 -.Fd #include <sys/time.h> |
|
64 -.Fd #include <event.h> |
|
65 -.Ft "struct event_base *" |
|
66 -.Fn "event_init" "void" |
|
67 -.Ft int |
|
68 -.Fn "event_dispatch" "void" |
|
69 -.Ft int |
|
70 -.Fn "event_loop" "int flags" |
|
71 -.Ft int |
|
72 -.Fn "event_loopexit" "struct timeval *tv" |
|
73 -.Ft void |
|
74 -.Fn "event_set" "struct event *ev" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" |
|
75 -.Ft int |
|
76 -.Fn "event_base_dispatch" "struct event_base *base" |
|
77 -.Ft int |
|
78 -.Fn "event_base_loop" "struct event_base *base" "int flags" |
|
79 -.Ft int |
|
80 -.Fn "event_base_loopexit" "struct event_base *base" "struct timeval *tv" |
|
81 -.Ft int |
|
82 -.Fn "event_base_set" "struct event_base *base" "struct event *" |
|
83 -.Ft void |
|
84 -.Fn "event_base_free" "struct event_base *base" |
|
85 -.Ft int |
|
86 -.Fn "event_add" "struct event *ev" "struct timeval *tv" |
|
87 -.Ft int |
|
88 -.Fn "event_del" "struct event *ev" |
|
89 -.Ft int |
|
90 -.Fn "event_once" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv" |
|
91 -.Ft int |
|
92 -.Fn "event_base_once" "struct event_base *base" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv" |
|
93 -.Ft int |
|
94 -.Fn "event_pending" "struct event *ev" "short event" "struct timeval *tv" |
|
95 -.Ft int |
|
96 -.Fn "event_initialized" "struct event *ev" |
|
97 -.Ft int |
|
98 -.Fn "event_priority_init" "int npriorities" |
|
99 -.Ft int |
|
100 -.Fn "event_priority_set" "struct event *ev" "int priority" |
|
101 -.Ft void |
|
102 -.Fn "evtimer_set" "struct event *ev" "void (*fn)(int, short, void *)" "void *arg" |
|
103 -.Ft void |
|
104 -.Fn "evtimer_add" "struct event *ev" "struct timeval *" |
|
105 -.Ft void |
|
106 -.Fn "evtimer_del" "struct event *ev" |
|
107 -.Ft int |
|
108 -.Fn "evtimer_pending" "struct event *ev" "struct timeval *tv" |
|
109 -.Ft int |
|
110 -.Fn "evtimer_initialized" "struct event *ev" |
|
111 -.Ft void |
|
112 -.Fn "signal_set" "struct event *ev" "int signal" "void (*fn)(int, short, void *)" "void *arg" |
|
113 -.Ft void |
|
114 -.Fn "signal_add" "struct event *ev" "struct timeval *" |
|
115 -.Ft void |
|
116 -.Fn "signal_del" "struct event *ev" |
|
117 -.Ft int |
|
118 -.Fn "signal_pending" "struct event *ev" "struct timeval *tv" |
|
119 -.Ft int |
|
120 -.Fn "signal_initialized" "struct event *ev" |
|
121 -.Ft "struct bufferevent *" |
|
122 -.Fn "bufferevent_new" "int fd" "evbuffercb readcb" "evbuffercb writecb" "everrorcb" "void *cbarg" |
|
123 -.Ft void |
|
124 -.Fn "bufferevent_free" "struct bufferevent *bufev" |
|
125 -.Ft int |
|
126 -.Fn "bufferevent_write" "struct bufferevent *bufev" "void *data" "size_t size" |
|
127 -.Ft int |
|
128 -.Fn "bufferevent_write_buffer" "struct bufferevent *bufev" "struct evbuffer *buf" |
|
129 -.Ft size_t |
|
130 -.Fn "bufferevent_read" "struct bufferevent *bufev" "void *data" "size_t size" |
|
131 -.Ft int |
|
132 -.Fn "bufferevent_enable" "struct bufferevent *bufev" "short event" |
|
133 -.Ft int |
|
134 -.Fn "bufferevent_disable" "struct bufferevent *bufev" "short event" |
|
135 -.Ft void |
|
136 -.Fn "bufferevent_settimeout" "struct bufferevent *bufev" "int timeout_read" "int timeout_write" |
|
137 -.Ft int |
|
138 -.Fn "bufferevent_base_set" "struct event_base *base" "struct bufferevent *bufev" |
|
139 -.Ft "struct evbuffer *" |
|
140 -.Fn "evbuffer_new" "void" |
|
141 -.Ft void |
|
142 -.Fn "evbuffer_free" "struct evbuffer *buf" |
|
143 -.Ft int |
|
144 -.Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size" |
|
145 -.Ft int |
|
146 -.Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src" |
|
147 -.Ft int |
|
148 -.Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..." |
|
149 -.Ft int |
|
150 -.Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap" |
|
151 -.Ft void |
|
152 -.Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size" |
|
153 -.Ft int |
|
154 -.Fn "evbuffer_write" "struct evbuffer *buf" "int fd" |
|
155 -.Ft int |
|
156 -.Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size" |
|
157 -.Ft "u_char *" |
|
158 -.Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size" |
|
159 -.Ft "char *" |
|
160 -.Fn "evbuffer_readline" "struct evbuffer *buf" |
|
161 -.Ft "struct evhttp *" |
|
162 -.Fn "evhttp_start" "const char *address" "u_short port" |
|
163 -.Ft "void" |
|
164 -.Fn "evhttp_free" "struct evhttp* http" |
|
165 -.Ft int |
|
166 -.Fa (*event_sigcb)(void) ; |
|
167 -.Ft volatile sig_atomic_t |
|
168 -.Fa event_gotsig ; |
|
169 -.Sh DESCRIPTION |
|
170 +.TH EVENT 3 "8 August 2000" "libevent 1.3e" "libevent Manual" |
|
171 +.SH NAME |
|
172 +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 |
|
173 +.SH LIBRARY |
|
174 +The libevent library (libevent, -levent) |
|
175 +.br |
|
176 +.SH SYNOPSIS |
|
177 +\fB#include <sys/time.h>\fP |
|
178 +.br |
|
179 +\fB#include <event.h>\fP |
|
180 +.sp |
|
181 +\fBstruct event_base* \fBevent_init\fR\fR(\fBvoid\fP\fR); |
|
182 +.br |
|
183 +\fBint \fBevent_dispatch\fR\fR(\fBvoid\fP\fR); |
|
184 +.br |
|
185 +\fBint \fBevent_loop\fR\fR(\fBint \fIflags\fP\fR); |
|
186 +.br |
|
187 +.BI "int event_loopexit(struct timeval* " tv ");" |
|
188 +.br |
|
189 +\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); |
|
190 +.br |
|
191 +\fBint \fBevent_base_dispatch\fR\fR(\fBstruct event_base* \fIbase\fP\fR); |
|
192 +.br |
|
193 +\fBint \fBevent_base_loop\fR\fR(\fBstruct event_base* \fIbase\fP\fR, \fBint \fIflags\fP\fR); |
|
194 +.br |
|
195 +\fBint \fBevent_base_loopexit\fR\fR(struct event_base* \fIbase\fP\fR, \fBstruct timeval* \fItv\fP\fR); |
|
196 +.br |
|
197 +\fBint \fBevent_base_set\fR\fR(struct event_base* \fIbase\fP\fR, \fBstruct event* \fIev\fP\fR); |
|
198 +.br |
|
199 +\fBvoid \fBevent_base_free\fR\fR(struct event_base* \fIbase\fP\fR); |
|
200 +.br |
|
201 +\fBint \fBevent_add\fR\fR(struct event* \fIev\fP\fR, \fBstruct timeval* \fItv\fP\fR); |
|
202 +.br |
|
203 +.\fBint \fBevent_del\fR\fR(struct event* \fIev\fP\fR); |
|
204 +.br |
|
205 +\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); |
|
206 +.br |
|
207 +\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); |
|
208 +.br |
|
209 +\fBint \fBevent_pending\fR\fR(struct event* \fIev\fP\fR, \fBshort \fIevent\fB\fR, \fBstruct timeval* \fItv\fP\fR); |
|
210 +.br |
|
211 +\fBint \fBevent_initialized\fR\fR(struct event* \fIev\fP\fR); |
|
212 +.br |
|
213 +\fBint \fBevent_priority_init\fR\fR (int \fInpriorities\fP\fR); |
|
214 +.br |
|
215 +\fBint \fBevent_priority_set\fR\fR (struct event* \fIev\fP\fR, \fBint \fIpriority\fP\fR); |
|
216 +.br |
|
217 +\fBvoid \fBevtimer_set\fR\fR (struct event* \fIev\fP\fR, \fBvoid \fI(*fn)(int, short, void*)\fB\fR, \fBvoid* \fIarg\fP\fR); |
|
218 +.br |
|
219 +\fBvoid \fBevtimer_add\fR\fR (struct event* \fIev\fP\fR, \fBstruct timeval* \fItv\fP\fR); |
|
220 +.br |
|
221 +\fBvoid \fBevtimer_del\fR\fR (struct event* \fIev\fP\fR); |
|
222 +.br |
|
223 +\fBint \fBevtimer_pending\fR\fR (struct event* \fIev\fP\fR, \fBstruct timeval* \fItv\fP\fR); |
|
224 +.br |
|
225 +\fBint \fBevtimer_initialized\fR\fR(struct event* \fIev\fP\fR); |
|
226 +.br |
|
227 +\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); |
|
228 +.br |
|
229 +\fBvoid \fBsignal_add\fR\fR (struct event* \fIev\fP\fR, \fBstruct timeval* \fItv\fP\fR); |
|
230 +.br |
|
231 +\fBvoid \fBsignal_del\fR\fR (struct event* \fIev\fP\fR); |
|
232 +.br |
|
233 +\fBint \fBsignal_pending\fR\fR(struct event* \fIev\fP\fR, \fBstruct timeval* \fItv\fP\fR); |
|
234 +.br |
|
235 +\fBint \fBsignal_initialized\fR\fR(struct event* \fIev\fP\fR); |
|
236 +.br |
|
237 +\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); |
|
238 +.br |
|
239 +\fBvoid \fBbufferevent_free\fR\fR(struct bufferevent* \fIbufev\fP\fR); |
|
240 +.br |
|
241 +\fBint \fBbufferevent_write\fR\fR(struct bufferevent* \fIbufev\fP\fR, \fBvoid* \fIdata\fP\fR, \fBsize_t \fIsize\fP\fR); |
|
242 +.br |
|
243 +\fBint \fBbufferevent_write_buffer\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBstruct evbuffer* \fIbuf\fP\fR); |
|
244 +.br |
|
245 +\fBsize_t \fBbufferevent_read\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBvoid* \fIdata\fP\fR, \fBsize_t \fIsize\fP\fR); |
|
246 +.br |
|
247 +\fBint \fBbufferevent_enable\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBshort \fIevent\fP\fR); |
|
248 +.br |
|
249 +\fBint \fBbufferevent_disable\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBshort \fIeven\fP\fR); |
|
250 +.br |
|
251 +\fBvoid \fBbufferevent_settimeout\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBint \fItimeout_read\fP\fR, \fBint \fItimeout_write\fP\fR); |
|
252 +.br |
|
253 +\fBint \fBbufferevent_base_set\fR\fR(\fBstruct event_base* \fIbase\fP\fR, \fBstruct bufferevent* \fIbufev\fP\fR); |
|
254 +.br |
|
255 +\fBstruct evbuffer* \fBevbuffer_new (\fBvoid\fP\fR); |
|
256 +.br |
|
257 +\fBvoid \fBvbuffer_free\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR); |
|
258 +.br |
|
259 +\fBint \fBevbuffer_add\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBconst void* \fIdata\fP\fR, \fBsize_t \fIsize\fP\fR); |
|
260 +.br |
|
261 +\fBint \fBevbuffer_add_buffer\fR\fR(\fBstruct evbuffer* \fIdst\fP\fR, \fBstruct evbuffer* \fIsrc\fP\fR); |
|
262 +.br |
|
263 +\fBint \fBevbuffer_add_printf\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBconst char* \fIfmt\fP\fR, \fB...\fP\fR); |
|
264 +.br |
|
265 +\fBint \fBevbuffer_add_vprintf\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBconst char* \fIfmt\fP\fR, \fBva_list \fIap\fP\fR); |
|
266 +.br |
|
267 +\fBvoid \fBevbuffer_drain\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBsize_t \fIsize\fP\fR); |
|
268 +.br |
|
269 +\fBint \fBevbuffer_write\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBint \fIfd\fP\fR); |
|
270 +.br |
|
271 +\fBint \fBevbuffer_read\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBint \fIfd\fP\fR, \fBint \fIsize\fP\fR); |
|
272 +.br |
|
273 +\fBu_char* \fBevbuffer_find\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR, \fBconst u_char* \fIdata\fP\fR, \fBsize_t \fIsize\fP\fR); |
|
274 +.br |
|
275 +\fBchar* \fBevbuffer_readline\fR\fR(\fBstruct evbuffer* \fIbuf\fP\fR); |
|
276 +.br |
|
277 +\fBint \fI(*event_sigcb)\fP\fR\fI(void)\fP\fR; |
|
278 +.br |
|
279 +\fBvolatile sig_atomic_t \fR\fRevent_gotsig\fP\fR; |
|
280 +.br |
|
281 +.SH DESCRIPTION |
|
282 The |
|
283 -.Nm event |
|
284 +\fIevent\fP\fR |
|
285 API provides a mechanism to execute a function when a specific event |
|
286 on a file descriptor occurs or after a given time has passed. |
|
287 -.Pp |
|
288 +.PP |
|
289 The |
|
290 -.Nm event |
|
291 +\fIevent\fP\fR |
|
292 API needs to be initialized with |
|
293 -.Fn event_init |
|
294 +\fBevent_init\fR |
|
295 before it can be used. |
|
296 -.Pp |
|
297 +.PP |
|
298 In order to process events, an application needs to call |
|
299 -.Fn event_dispatch . |
|
300 +\fIevent_dispatch\fP\fR . |
|
301 This function only returns on error, and should replace the event core |
|
302 of the application program. |
|
303 -.Pp |
|
304 +.PP |
|
305 In order to avoid races in signal handlers, the |
|
306 -.Nm event |
|
307 +\fIevent\fP\fR |
|
308 API provides two variables: |
|
309 -.Va event_sigcb |
|
310 +\fIevent_sigcb\fP\fR |
|
311 and |
|
312 -.Va event_gotsig . |
|
313 +\fIevent_gotsig\fP\fR. |
|
314 A signal handler |
|
315 sets |
|
316 -.Va event_gotsig |
|
317 +\fIevent_gotsig\fP\fR |
|
318 to indicate that a signal has been received. |
|
319 The application sets |
|
320 -.Va event_sigcb |
|
321 +\fIevent_sigcb\fP\fR |
|
322 to a callback function. |
|
323 After the signal handler sets |
|
324 -.Va event_gotsig , |
|
325 -.Nm event_dispatch |
|
326 +\fIevent_gotsig\fP\fR, |
|
327 +\fBevent_dispatch()\fP\fR |
|
328 will execute the callback function to process received signals. |
|
329 The callback returns 1 when no events are registered any more. |
|
330 It can return \-1 to indicate an error to the |
|
331 -.Nm event |
|
332 +\fIevent\fP\fR |
|
333 library, causing |
|
334 -.Fn event_dispatch |
|
335 +\fBevent_dispatch\fP\fR |
|
336 to terminate with |
|
337 -.Va errno |
|
338 -set to |
|
339 -.Er EINTR . |
|
340 -.Pp |
|
341 +\fIerrno\fP\fR |
|
342 +set to EINTR. |
|
343 +.PO |
|
344 The |
|
345 -.Nm event_loop |
|
346 +\fIevent_loop\fP\fR |
|
347 function provides an interface for single pass execution of pending |
|
348 events. |
|
349 The flags |
|
350 -.Va EVLOOP_ONCE |
|
351 -and |
|
352 -.Va EVLOOP_NONBLOCK |
|
353 -are recognized. |
|
354 +EVLOOP_ONCE and EVLOOP_NONBLOCK are recognized. |
|
355 The |
|
356 -.Nm event_loopexit |
|
357 +\fIevent_loopexit\fP\fR |
|
358 function allows the loop to be terminated after some amount of time |
|
359 has passed. |
|
360 The parameter indicates the time after which the loop should terminate. |
|
361 -.Pp |
|
362 +.PP |
|
363 It is the responsibility of the caller to provide these functions with |
|
364 pre-allocated event structures. |
|
365 -.Pp |
|
366 +.PP |
|
367 The function |
|
368 -.Fn event_set |
|
369 +\fBevent_set\fP\fR |
|
370 prepares the event structure |
|
371 -.Fa ev |
|
372 +\fIev\fP\fR |
|
373 to be used in future calls to |
|
374 -.Fn event_add |
|
375 +\fBevent_add\fP\fR |
|
376 and |
|
377 -.Fn event_del . |
|
378 +\fBevent_del\fP\fR . |
|
379 The event will be prepared to call the function specified by the |
|
380 -.Fa fn |
|
381 +\fIfn\fP\fR |
|
382 argument with an |
|
383 -.Fa int |
|
384 +\fIint\fP\fR |
|
385 argument indicating the file descriptor, a |
|
386 -.Fa short |
|
387 +\fIshort\fP\fR |
|
388 argument indicating the type of event, and a |
|
389 -.Fa void * |
|
390 +\fIvoid*\fP\fR |
|
391 argument given in the |
|
392 -.Fa arg |
|
393 +\fIarg\fP\fR |
|
394 argument. |
|
395 -The |
|
396 -.Fa fd |
|
397 +The \fIfd\fP\fR |
|
398 indicates the file descriptor that should be monitored for events. |
|
399 -The events can be either |
|
400 -.Va EV_READ , |
|
401 -.Va EV_WRITE , |
|
402 -or both, |
|
403 +The events can be either EV_READ, EV_WRITE , or both, |
|
404 indicating that an application can read or write from the file descriptor |
|
405 respectively without blocking. |
|
406 -.Pp |
|
407 +.PP |
|
408 The function |
|
409 -.Fa fn |
|
410 +\fIfn\fP\fR |
|
411 will be called with the file descriptor that triggered the event and |
|
412 -the type of event which will be either |
|
413 -.Va EV_TIMEOUT , |
|
414 -.Va EV_SIGNAL , |
|
415 -.Va EV_READ , |
|
416 -or |
|
417 -.Va EV_WRITE . |
|
418 -The additional flag |
|
419 -.Va EV_PERSIST |
|
420 -makes an |
|
421 -.Fn event_add |
|
422 -persistent until |
|
423 -.Fn event_del |
|
424 +the type of event which will be either EV_TIMEOUT, EV_SIGNAL, |
|
425 +EV_READ, or EV_WRITE. The additional flag EV_PERSIST makes an |
|
426 +\fIevent_add\fP\fR persistent until |
|
427 +\fIevent_del\fP\fR |
|
428 has been called. |
|
429 -.Pp |
|
430 +.PP |
|
431 Once initialized, the |
|
432 -.Fa ev |
|
433 +\fIev\fP\fR |
|
434 structure can be used repeatedly with |
|
435 -.Fn event_add |
|
436 +\fIevent_add\fP\fR |
|
437 and |
|
438 -.Fn event_del |
|
439 +\fIevent_del\fP\fR |
|
440 and does not need to be reinitialized unless the function called and/or |
|
441 the argument to it are to be changed. |
|
442 However, when an |
|
443 -.Fa ev |
|
444 +\fIev\fP\fR |
|
445 structure has been added to libevent using |
|
446 -.Fn event_add |
|
447 +\fIevent_add\fP\fR |
|
448 the structure must persist until the event occurs (assuming |
|
449 -.Fa EV_PERSIST |
|
450 -is not set) or is removed |
|
451 -using |
|
452 -.Fn event_del . |
|
453 +EV_PERSIST is not set) or is removed using |
|
454 +\fIevent_del\fP\fR . |
|
455 You may not reuse the same |
|
456 -.Fa ev |
|
457 +\fIev\fP\fR |
|
458 structure for multiple monitored descriptors; each descriptor |
|
459 -needs its own |
|
460 -.Fa ev . |
|
461 -.Pp |
|
462 +needs its own \fIev\fP\fR . |
|
463 +.PP |
|
464 The function |
|
465 -.Fn event_add |
|
466 +\fIevent_add\fP\fR |
|
467 schedules the execution of the |
|
468 -.Fa ev |
|
469 +\fIev\fP\fR |
|
470 event when the event specified in |
|
471 -.Fn event_set |
|
472 +\fBevent_set\fP\fR |
|
473 occurs or in at least the time specified in the |
|
474 -.Fa tv . |
|
475 +\fItv\fP\fR . |
|
476 If |
|
477 -.Fa tv |
|
478 -is |
|
479 -.Dv NULL , |
|
480 -no timeout occurs and the function will only be called |
|
481 +\fItv\fP\fR |
|
482 +is NULL, no timeout occurs and the function will only be called |
|
483 if a matching event occurs on the file descriptor. |
|
484 The event in the |
|
485 -.Fa ev |
|
486 +\fIev\fP\fR |
|
487 argument must be already initialized by |
|
488 -.Fn event_set |
|
489 +\fIevent_set\fP\fR |
|
490 and may not be used in calls to |
|
491 -.Fn event_set |
|
492 +\fIevent_set\fP\fR |
|
493 until it has timed out or been removed with |
|
494 -.Fn event_del . |
|
495 +\fIevent_del\fP\fR . |
|
496 If the event in the |
|
497 -.Fa ev |
|
498 +\fIev\fP\fR |
|
499 argument already has a scheduled timeout, the old timeout will be |
|
500 replaced by the new one. |
|
501 -.Pp |
|
502 +.PP |
|
503 The function |
|
504 -.Fn event_del |
|
505 +\fIevent_del\fP\fR |
|
506 will cancel the event in the argument |
|
507 -.Fa ev . |
|
508 +\fIev\fP\fR . |
|
509 If the event has already executed or has never been added |
|
510 the call will have no effect. |
|
511 -.Pp |
|
512 +.PP |
|
513 The function |
|
514 -.Fn event_once |
|
515 +\fIevent_once\fP\fR |
|
516 is similar to |
|
517 -.Fn event_set . |
|
518 +\fIevent_set\fP\fR. |
|
519 However, it schedules a callback to be called exactly once and does not |
|
520 require the caller to prepare an |
|
521 -.Fa event |
|
522 +\fIevent\fP\fR |
|
523 structure. |
|
524 -This function supports |
|
525 -.Fa EV_TIMEOUT , |
|
526 -.Fa EV_READ , |
|
527 -and |
|
528 -.Fa EV_WRITE . |
|
529 -.Pp |
|
530 +This function supports EV_TIMEOUT, EV_READ, and EV_WRITE. |
|
531 +.PP |
|
532 The |
|
533 -.Fn event_pending |
|
534 +\fIevent_pending\fP\fR |
|
535 function can be used to check if the event specified by |
|
536 -.Fa event |
|
537 +\fIevent\fP\fR |
|
538 is pending to run. |
|
539 -If |
|
540 -.Va EV_TIMEOUT |
|
541 -was specified and |
|
542 -.Fa tv |
|
543 -is not |
|
544 -.Dv NULL , |
|
545 +If EV_TIMEOUT was specified and |
|
546 +\fItv\fP\fR |
|
547 +is not NULL , |
|
548 the expiration time of the event will be returned in |
|
549 -.Fa tv . |
|
550 -.Pp |
|
551 +\fItv\fP\fR . |
|
552 +.PP |
|
553 The |
|
554 -.Fn event_initialized |
|
555 +\fIevent_initialized\fP\fR |
|
556 macro can be used to check if an event has been initialized. |
|
557 -.Pp |
|
558 +.PP |
|
559 The functions |
|
560 -.Fn evtimer_set , |
|
561 -.Fn evtimer_add , |
|
562 -.Fn evtimer_del , |
|
563 -.Fn evtimer_initialized , |
|
564 +\fIevtimer_set()\fP\fR, |
|
565 +\fIevtimer_add()\fP\fR, |
|
566 +\fIevtimer_del()\fP\fR, |
|
567 +\fIevtimer_initialized()\fP\fR, |
|
568 and |
|
569 -.Fn evtimer_pending |
|
570 +\fIevtimer_pending()\fP\fR |
|
571 are abbreviations for common situations where only a timeout is required. |
|
572 The file descriptor passed will be \-1, and the event type will be |
|
573 -.Va EV_TIMEOUT . |
|
574 -.Pp |
|
575 +EV_TIMEOUT . |
|
576 +.PP |
|
577 The functions |
|
578 -.Fn signal_set , |
|
579 -.Fn signal_add , |
|
580 -.Fn signal_del , |
|
581 -.Fn signal_initialized , |
|
582 +\fIsignal_set()\fP\fR, |
|
583 +\fIsignal_add()\fP]\fR, |
|
584 +\fIsignal_del()\fP\fR , |
|
585 +\fIsignal_initialized()\fP\fR, |
|
586 and |
|
587 -.Fn signal_pending |
|
588 +\fIsignal_pending()\fP\fR |
|
589 are abbreviations. |
|
590 -The event type will be a persistent |
|
591 -.Va EV_SIGNAL . |
|
592 +The event type will be a persistent EV_SIGNAL . |
|
593 That means |
|
594 -.Fn signal_set |
|
595 -adds |
|
596 -.Va EV_PERSIST . |
|
597 -.Pp |
|
598 +\fIsignal_set\fP\fR adds EV_PERSIST . |
|
599 +.PP |
|
600 It is possible to disable support for |
|
601 -.Va epoll , kqueue , devpoll , poll |
|
602 -or |
|
603 -.Va select |
|
604 +epoll, kqueue, devpoll, event ports, poll or select |
|
605 by setting the environment variable |
|
606 -.Va EVENT_NOEPOLL , EVENT_NOKQUEUE , EVENT_NODEVPOLL , EVENT_NOPOLL |
|
607 -or |
|
608 -.Va EVENT_NOSELECT , |
|
609 -respectively. |
|
610 +EVENT_NOEPOLL, EVENT_NOKQUEUE, EVENT_NODEVPOLL, EVENT_NOEVPORT, |
|
611 +EVENT_NOPOLL or EVENT_NOSELECT, respectively. |
|
612 By setting the environment variable |
|
613 -.Va EVENT_SHOW_METHOD , |
|
614 -.Nm libevent |
|
615 +EVENT_SHOW_METHOD, |
|
616 +\fIlibevent\fP\fR |
|
617 displays the kernel notification method that it uses. |
|
618 -.Sh EVENT PRIORITIES |
|
619 +.SH EVENT PRIORITIES |
|
620 By default |
|
621 -.Nm libevent |
|
622 +\fIlibevent\fP\fR |
|
623 schedules all active events with the same priority. |
|
624 However, sometimes it is desirable to process some events with a higher |
|
625 priority than others. |
|
626 For that reason, |
|
627 -.Nm libevent |
|
628 +\fIlibevent\fP\fR |
|
629 supports strict priority queues. |
|
630 Active events with a lower priority are always processed before events |
|
631 with a higher priority. |
|
632 -.Pp |
|
633 +.PP |
|
634 The number of different priorities can be set initially with the |
|
635 -.Fn event_priority_init |
|
636 +\fIevent_priority_init()\fP\fR |
|
637 function. |
|
638 This function should be called before the first call to |
|
639 -.Fn event_dispatch . |
|
640 +\fIevent_dispatch()\fP\fR . |
|
641 The |
|
642 -.Fn event_priority_set |
|
643 +\fIevent_priority_set()\fP\fR |
|
644 function can be used to assign a priority to an event. |
|
645 By default, |
|
646 -.Nm libevent |
|
647 +\fIlibevent\fP\fR |
|
648 assigns the middle priority to all events unless their priority |
|
649 is explicitly set. |
|
650 -.Sh THREAD SAFE EVENTS |
|
651 -.Nm Libevent |
|
652 +.SH THREAD SAFE EVENTS |
|
653 +\fIlibevent\fP\fR |
|
654 has experimental support for thread-safe events. |
|
655 When initializing the library via |
|
656 -.Fn event_init , |
|
657 +\fIevent_init()\fP\fR, |
|
658 an event base is returned. |
|
659 This event base can be used in conjunction with calls to |
|
660 -.Fn event_base_set , |
|
661 -.Fn event_base_dispatch , |
|
662 -.Fn event_base_loop , |
|
663 -.Fn event_base_loopexit , |
|
664 -.Fn bufferevent_base_set |
|
665 +\fIevent_base_set()\fP\fR, |
|
666 +\fIevent_base_dispatch()\fP\fR, |
|
667 +\fIevent_base_loop()\fP\fR, |
|
668 +\fIevent_base_loopexit()\fP\fR, |
|
669 +\fIbufferevent_base_set()\fP\fR |
|
670 and |
|
671 -.Fn event_base_free . |
|
672 -.Fn event_base_set |
|
673 +\fIevent_base_free()\fP\fR. |
|
674 +\fIevent_base_set()\fP\fR |
|
675 should be called after preparing an event with |
|
676 -.Fn event_set , |
|
677 +\fIevent_set()\fP\fR, |
|
678 as |
|
679 -.Fn event_set |
|
680 +\fIevent_set()\fP\fR |
|
681 assigns the provided event to the most recently created event base. |
|
682 -.Fn bufferevent_base_set |
|
683 +\fIbufferevent_base_set()\fP\fR |
|
684 should be called after preparing a bufferevent with |
|
685 -.Fn bufferevent_new . |
|
686 -.Fn event_base_free |
|
687 +\fIbufferevent_new()\fP\fR. |
|
688 +\fIevent_base_free()\fP\fR |
|
689 should be used to free memory associated with the event base |
|
690 when it is no longer needed. |
|
691 -.Sh BUFFERED EVENTS |
|
692 -.Nm libevent |
|
693 +.SH BUFFERED EVENTS |
|
694 +\fIlibevent\fP\fR |
|
695 provides an abstraction on top of the regular event callbacks. |
|
696 This abstraction is called a |
|
697 -.Va "buffered event" . |
|
698 +\fB"buffered event"\fP\fR. |
|
699 A buffered event provides input and output buffers that get filled |
|
700 and drained automatically. |
|
701 The user of a buffered event no longer deals directly with the IO, |
|
702 but instead is reading from input and writing to output buffers. |
|
703 -.Pp |
|
704 +.PP |
|
705 A new bufferevent is created by |
|
706 -.Fn bufferevent_new . |
|
707 +\fIbufferevent_new()\fP\fR. |
|
708 The parameter |
|
709 -.Fa fd |
|
710 +\fIfd\fP\fR |
|
711 specifies the file descriptor from which data is read and written to. |
|
712 This file descriptor is not allowed to be a |
|
713 -.Xr pipe 2 . |
|
714 +\fBpipe(2)\fR. |
|
715 The next three parameters are callbacks. |
|
716 The read and write callback have the following form: |
|
717 -.Ft void |
|
718 -.Fn "(*cb)" "struct bufferevent *bufev" "void *arg" . |
|
719 +\fBvoid \fB(*cb)\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBvoid* \fIarg\fP\fR). |
|
720 The error callback has the following form: |
|
721 -.Ft void |
|
722 -.Fn "(*cb)" "struct bufferevent *bufev" "short what" "void *arg" . |
|
723 +\fBvoid \fB(*cb)\fR\fR(\fBstruct bufferevent* \fIbufev\fP\fR, \fBshort \fIwhat\fP\fR, \fBvoid* \fIarg\fP\fR). |
|
724 The argument is specified by the fourth parameter |
|
725 -.Fa "cbarg" . |
|
726 +\fIcbarg\fP\fR. |
|
727 A |
|
728 -.Fa bufferevent struct |
|
729 +\fIbufferevent\fP\fR struct |
|
730 pointer is returned on success, NULL on error. |
|
731 Both the read and the write callback may be NULL. |
|
732 The error callback has to be always provided. |
|
733 -.Pp |
|
734 +.PP |
|
735 Once initialized, the bufferevent structure can be used repeatedly with |
|
736 -bufferevent_enable() and bufferevent_disable(). |
|
737 -The flags parameter can be a combination of |
|
738 -.Va EV_READ |
|
739 -and |
|
740 -.Va EV_WRITE . |
|
741 +\fIbufferevent_enable()\fP\fR and \fIbufferevent_disable()\fP\fR. |
|
742 +The \fIflags\fP\fR parameter can be a combination of |
|
743 +EV_READ and EV_WRITE . |
|
744 When read enabled the bufferevent will try to read from the file |
|
745 descriptor and call the read callback. |
|
746 The write callback is executed |
|
747 whenever the output buffer is drained below the write low watermark, |
|
748 -which is |
|
749 -.Va 0 |
|
750 -by default. |
|
751 -.Pp |
|
752 +which is 0 by default. |
|
753 +.PP |
|
754 The |
|
755 -.Fn bufferevent_write |
|
756 +\fIbufferevent_write()\fP\fR |
|
757 function can be used to write data to the file descriptor. |
|
758 The data is appended to the output buffer and written to the descriptor |
|
759 automatically as it becomes available for writing. |
|
760 -.Fn bufferevent_write |
|
761 +\fIbufferevent_write()\fP\fR |
|
762 returns 0 on success or \-1 on failure. |
|
763 The |
|
764 -.Fn bufferevent_read |
|
765 +\fIbufferevent_read()\fP\fR |
|
766 function is used to read data from the input buffer, |
|
767 returning the amount of data read. |
|
768 -.Pp |
|
769 +.PP |
|
770 If multiple bases are in use, bufferevent_base_set() must be called before |
|
771 enabling the bufferevent for the first time. |
|
772 -.Sh NON-BLOCKING HTTP SUPPORT |
|
773 -.Nm libevent |
|
774 -provides a very thin HTTP layer that can be used both to host an HTTP |
|
775 -server and also to make HTTP requests. |
|
776 -An HTTP server can be created by calling |
|
777 -.Fn evhttp_start . |
|
778 -When the HTTP server is no longer used, it can be freed via |
|
779 -.Fn evhttp_free . |
|
780 -.Pp |
|
781 -To be notified of HTTP requests, a user needs to register callbacks with the |
|
782 -HTTP server. |
|
783 -This can be done by calling |
|
784 -.Fn evhttp_set_cb . |
|
785 -The second argument is the URI for which a callback is being registered. |
|
786 -The corresponding callback will receive an |
|
787 -.Va struct evhttp_request |
|
788 -object that contains all information about the request. |
|
789 -.Pp |
|
790 -This section does not document all the possible function calls; please |
|
791 -check |
|
792 -.Va event.h |
|
793 -for the public interfaces. |
|
794 -.Sh RETURN VALUES |
|
795 +.SH RETURN VALUES |
|
796 Upon successful completion |
|
797 -.Fn event_add |
|
798 +\fIevent_add()\fP\fR |
|
799 and |
|
800 -.Fn event_del |
|
801 +\fIevent_del()\fP\fR |
|
802 return 0. |
|
803 Otherwise, \-1 is returned and the global variable errno is |
|
804 set to indicate the error. |
|
805 -.Sh SEE ALSO |
|
806 -.Xr kqueue 2 , |
|
807 -.Xr poll 2 , |
|
808 -.Xr select 2 , |
|
809 -.Xr evdns 3 , |
|
810 -.Xr timeout 9 |
|
811 -.Sh HISTORY |
|
812 +.SH SEE ALSO |
|
813 +\fBpoll(2)\fR, |
|
814 +\fBselect(3C)\fR, |
|
815 +\fBport_create(3C)\fR, |
|
816 +\fBtimeout(9f)\fR. |
|
817 +.SH HISTORY |
|
818 The |
|
819 -.Nm event |
|
820 +\fIlibevent\fR |
|
821 API manpage is based on the |
|
822 -.Xr timeout 9 |
|
823 +\fBtimeout(9)\fR |
|
824 manpage by Artur Grabowski. |
|
825 The port of |
|
826 -.Nm libevent |
|
827 +\fBlibevent\fP\fR |
|
828 to Windows is due to Michael A. Davis. |
|
829 Support for real-time signals is due to Taral. |
|
830 -.Sh AUTHORS |
|
831 +.SH AUTHORS |
|
832 The |
|
833 -.Nm event |
|
834 +\fIevent\fP\fR |
|
835 library was written by Niels Provos. |
|
836 -.Sh BUGS |
|
837 +.SH BUGS |
|
838 This documentation is neither complete nor authoritative. |
|
839 If you are in doubt about the usage of this API then |
|
840 check the source code to find out how it works, write |
|
841 up the missing piece of documentation and send it to |
|
842 me for inclusion in this man page. |
|
843 + |