← Back to branch summary

~ubuntu-branches/ubuntu/trusty/mysql-5.6/trusty

« back to all changes in this revision

Viewing changes to .pc/spelling.patch/libevent/event.3

  • Committer: Package Import Robot
  • Author(s): James Page, Akhil Mohan, Bjoern Boschman
  • Date: 2014-02-12 11:54:27 UTC
  • Revision ID: package-import@ubuntu.com-20140212115427-0vst0nnto99pc2su
Tags: 5.6.15-0ubuntu1
[ Akhil Mohan ]
* added libmysqlclient.so link to libmysqlclient18.1-dev package
* revisited patches in d/patches/series; removed extra patches not needed
* some patches were modified to handle 5.6 issues
* mysql-server-5.6 and mysql-client-5.6 now depend on mysql-common (>= 5.5)
* mysql-server-5.6 now provides only virtual-mysql-server
* mysql-client-5.6 now provides only virtual-mysql-client
* MySQL 5.6 now contains mysql-common-5.6 which is only suggested
* moved mysql-common/etc/mysql/my.cnf to
    mysql-common-5.6/usr/share/mysql/my.cnf
* MySQL 5.6 now gives libmysqlclient18.1, libmysqlclient18.1-dev,
    libmysqld-5.6-dev and libmysqld-5.6-pic
* libmysqlclient18.1-dev, libmysqld-5.6-dev and libmysqld-5.6-pic packages
    conflict with their respective counterparts from MySQL 5.5
* link traversal for libmysqlclient is
    libmysqlclient.so (contained in libmysqclient18.1-dev)  ->
    libmysqlclient.so.18 (contained in libmysqclient18.1)   ->
    libmysqlclient.so.18.1 (contained in libmysqclient18.1) ->
    libmysqlclient.so.18.1.0 (contained in libmysqclient18.1)
* Placeholder packages mysql-server, mysql-client, mysql-testsuite 
  have been discontinued
* d/rules, d/control removed gcc-4.4 dependency and disable X86 assembly in
  taocrypt.
  - Cherry-pick from Debian svn r2231 with thanks to Clint Byrum.
* changed mirror to download source tar
* replaced mysql_install_db script with small shell script to create
  root accounts. This avoids creating anonymous users which were
  security concern.
* Docs/mysql.info has been removed in the mysql 5.6.15 source
* removed debian/repack.* and 'DFSG and repacking' section in
  debian/README.source because repack not needed
* dropped '+dfsg' from version in changelog since there is no repack
* simplified debian/watch since there is no repack
* removed redundant *_r* links to mysql client library in libmysqlclient18
  and libmysqlclient-dev packages
* updated debian/control to allow mysql-*-5.6 packages upgrade/ replace
  an existing installation of mysql-*-5.5 packages
* modified debian/rules to use system zlib library, install additional
  man pages and remove execute bit on few test and result files
* added patches to fix link path in man page mysql_client_test_embedded.1
  and mysqltest_embedded.1
* added man page for mysql_config_pic at debian/additions/mysql_config_pic.1
* added man page for mysql_embedded at debian/additions/mysql_embedded.1
* moved libmysqlcient.so link from libmysqlclient18 to libmysqlclient-dev
  based on lintian warning non-dev-pkg-with-shlib-symlink
* moved mysql_client_test_embedded binary from mysql-testsuite-5.6 
  package to mysql-client-5.6 package
* moved mysql_config_editor.1 man page to mysql-client-5.6 package
* moved mysql_embedded from mysql-testsuite-5.6 package to mysql-client-5.6
  package
* moved mysqltest_embedded binary from mysql-testsuite-5.6
  package to mysql-server-5.6 package
* removed absolute path for mysql_install_db script in mysql-server-5.6
  postinst script based on lintian warning

[ Bjoern Boschman ]
* Initial release of mysql-5.6 package.
* mysql_install_db is now a perl script. Do not run it with bash.
* added innodb_data_file_path to my.cnf for mysql-5.1 => mysql-5.6 upgrade
  path.
* added multiarch support 
* do not include .a files within libmysqlclient18

Show diffs side-by-side

added added

removed removed

Lines of Context:
.pc/spelling.patch/libevent/event.3
 
1
.\"     $OpenBSD: event.3,v 1.4 2002/07/12 18:50:48 provos Exp $
 
2
.\"
 
3
.\" Copyright (c) 2000 Artur Grabowski <art@openbsd.org>
 
4
.\" All rights reserved.
 
5
.\"
 
6
.\" Redistribution and use in source and binary forms, with or without
 
7
.\" modification, are permitted provided that the following conditions
 
8
.\" are met:
 
9
.\"
 
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.
 
17
.\"
 
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.
 
28
.\"
 
29
.Dd August 8, 2000
 
30
.Dt EVENT 3
 
31
.Os
 
32
.Sh NAME
 
33
.Nm event_init ,
 
34
.Nm event_dispatch ,
 
35
.Nm event_loop ,
 
36
.Nm event_loopexit ,
 
37
.Nm event_loopbreak ,
 
38
.Nm event_set ,
 
39
.Nm event_base_dispatch ,
 
40
.Nm event_base_loop ,
 
41
.Nm event_base_loopexit ,
 
42
.Nm event_base_loopbreak ,
 
43
.Nm event_base_set ,
 
44
.Nm event_base_free ,
 
45
.Nm event_add ,
 
46
.Nm event_del ,
 
47
.Nm event_once ,
 
48
.Nm event_base_once ,
 
49
.Nm event_pending ,
 
50
.Nm event_initialized ,
 
51
.Nm event_priority_init ,
 
52
.Nm event_priority_set ,
 
53
.Nm evtimer_set ,
 
54
.Nm evtimer_add ,
 
55
.Nm evtimer_del ,
 
56
.Nm evtimer_pending ,
 
57
.Nm evtimer_initialized ,
 
58
.Nm signal_set ,
 
59
.Nm signal_add ,
 
60
.Nm signal_del ,
 
61
.Nm signal_pending ,
 
62
.Nm signal_initialized ,
 
63
.Nm bufferevent_new ,
 
64
.Nm bufferevent_free ,
 
65
.Nm bufferevent_write ,
 
66
.Nm bufferevent_write_buffer ,
 
67
.Nm bufferevent_read ,
 
68
.Nm bufferevent_enable ,
 
69
.Nm bufferevent_disable ,
 
70
.Nm bufferevent_settimeout ,
 
71
.Nm bufferevent_base_set ,
 
72
.Nm evbuffer_new ,
 
73
.Nm evbuffer_free ,
 
74
.Nm evbuffer_add ,
 
75
.Nm evbuffer_add_buffer ,
 
76
.Nm evbuffer_add_printf ,
 
77
.Nm evbuffer_add_vprintf ,
 
78
.Nm evbuffer_drain ,
 
79
.Nm evbuffer_write ,
 
80
.Nm evbuffer_read ,
 
81
.Nm evbuffer_find ,
 
82
.Nm evbuffer_readline ,
 
83
.Nm evhttp_new ,
 
84
.Nm evhttp_bind_socket ,
 
85
.Nm evhttp_free
 
86
.Nd execute a function when a specific event occurs
 
87
.Sh SYNOPSIS
 
88
.Fd #include <sys/time.h>
 
89
.Fd #include <event.h>
 
90
.Ft "struct event_base *"
 
91
.Fn "event_init" "void"
 
92
.Ft int
 
93
.Fn "event_dispatch" "void"
 
94
.Ft int
 
95
.Fn "event_loop" "int flags"
 
96
.Ft int
 
97
.Fn "event_loopexit" "struct timeval *tv"
 
98
.Ft int
 
99
.Fn "event_loopbreak" "void"
 
100
.Ft void
 
101
.Fn "event_set" "struct event *ev" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg"
 
102
.Ft int
 
103
.Fn "event_base_dispatch" "struct event_base *base"
 
104
.Ft int
 
105
.Fn "event_base_loop" "struct event_base *base" "int flags"
 
106
.Ft int
 
107
.Fn "event_base_loopexit" "struct event_base *base" "struct timeval *tv"
 
108
.Ft int
 
109
.Fn "event_base_loopbreak" "struct event_base *base"
 
110
.Ft int
 
111
.Fn "event_base_set" "struct event_base *base" "struct event *"
 
112
.Ft void
 
113
.Fn "event_base_free" "struct event_base *base"
 
114
.Ft int
 
115
.Fn "event_add" "struct event *ev" "struct timeval *tv"
 
116
.Ft int
 
117
.Fn "event_del" "struct event *ev"
 
118
.Ft int
 
119
.Fn "event_once" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv"
 
120
.Ft int
 
121
.Fn "event_base_once" "struct event_base *base" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv"
 
122
.Ft int
 
123
.Fn "event_pending" "struct event *ev" "short event" "struct timeval *tv"
 
124
.Ft int
 
125
.Fn "event_initialized" "struct event *ev"
 
126
.Ft int
 
127
.Fn "event_priority_init" "int npriorities"
 
128
.Ft int
 
129
.Fn "event_priority_set" "struct event *ev" "int priority"
 
130
.Ft void
 
131
.Fn "evtimer_set" "struct event *ev" "void (*fn)(int, short, void *)" "void *arg"
 
132
.Ft void
 
133
.Fn "evtimer_add" "struct event *ev" "struct timeval *"
 
134
.Ft void
 
135
.Fn "evtimer_del" "struct event *ev"
 
136
.Ft int
 
137
.Fn "evtimer_pending" "struct event *ev" "struct timeval *tv"
 
138
.Ft int
 
139
.Fn "evtimer_initialized" "struct event *ev"
 
140
.Ft void
 
141
.Fn "signal_set" "struct event *ev" "int signal" "void (*fn)(int, short, void *)" "void *arg"
 
142
.Ft void
 
143
.Fn "signal_add" "struct event *ev" "struct timeval *"
 
144
.Ft void
 
145
.Fn "signal_del" "struct event *ev"
 
146
.Ft int
 
147
.Fn "signal_pending" "struct event *ev" "struct timeval *tv"
 
148
.Ft int
 
149
.Fn "signal_initialized" "struct event *ev"
 
150
.Ft "struct bufferevent *"
 
151
.Fn "bufferevent_new" "int fd" "evbuffercb readcb" "evbuffercb writecb" "everrorcb" "void *cbarg"
 
152
.Ft void
 
153
.Fn "bufferevent_free" "struct bufferevent *bufev"
 
154
.Ft int
 
155
.Fn "bufferevent_write" "struct bufferevent *bufev" "void *data" "size_t size"
 
156
.Ft int
 
157
.Fn "bufferevent_write_buffer" "struct bufferevent *bufev" "struct evbuffer *buf"
 
158
.Ft size_t
 
159
.Fn "bufferevent_read" "struct bufferevent *bufev" "void *data" "size_t size"
 
160
.Ft int
 
161
.Fn "bufferevent_enable" "struct bufferevent *bufev" "short event"
 
162
.Ft int
 
163
.Fn "bufferevent_disable" "struct bufferevent *bufev" "short event"
 
164
.Ft void
 
165
.Fn "bufferevent_settimeout" "struct bufferevent *bufev" "int timeout_read" "int timeout_write"
 
166
.Ft int
 
167
.Fn "bufferevent_base_set" "struct event_base *base" "struct bufferevent *bufev"
 
168
.Ft "struct evbuffer *"
 
169
.Fn "evbuffer_new" "void"
 
170
.Ft void
 
171
.Fn "evbuffer_free" "struct evbuffer *buf"
 
172
.Ft int
 
173
.Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size"
 
174
.Ft int
 
175
.Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src"
 
176
.Ft int
 
177
.Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..."
 
178
.Ft int
 
179
.Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap"
 
180
.Ft void
 
181
.Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size"
 
182
.Ft int
 
183
.Fn "evbuffer_write" "struct evbuffer *buf" "int fd"
 
184
.Ft int
 
185
.Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size"
 
186
.Ft "u_char *"
 
187
.Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size"
 
188
.Ft "char *"
 
189
.Fn "evbuffer_readline" "struct evbuffer *buf"
 
190
.Ft "struct evhttp *"
 
191
.Fn "evhttp_new" "struct event_base *base"
 
192
.Ft int
 
193
.Fn "evhttp_bind_socket" "struct evhttp *http" "const char *address" "u_short port"
 
194
.Ft "void"
 
195
.Fn "evhttp_free" "struct evhttp *http"
 
196
.Ft int
 
197
.Fa (*event_sigcb)(void) ;
 
198
.Ft volatile sig_atomic_t
 
199
.Fa event_gotsig ;
 
200
.Sh DESCRIPTION
 
201
The
 
202
.Nm event
 
203
API provides a mechanism to execute a function when a specific event
 
204
on a file descriptor occurs or after a given time has passed.
 
205
.Pp
 
206
The
 
207
.Nm event
 
208
API needs to be initialized with
 
209
.Fn event_init
 
210
before it can be used.
 
211
.Pp
 
212
In order to process events, an application needs to call
 
213
.Fn event_dispatch .
 
214
This function only returns on error, and should replace the event core
 
215
of the application program.
 
216
.Pp
 
217
The function
 
218
.Fn event_set
 
219
prepares the event structure
 
220
.Fa ev
 
221
to be used in future calls to
 
222
.Fn event_add
 
223
and
 
224
.Fn event_del .
 
225
The event will be prepared to call the function specified by the
 
226
.Fa fn
 
227
argument with an
 
228
.Fa int
 
229
argument indicating the file descriptor, a
 
230
.Fa short
 
231
argument indicating the type of event, and a
 
232
.Fa void *
 
233
argument given in the
 
234
.Fa arg
 
235
argument.
 
236
The
 
237
.Fa fd
 
238
indicates the file descriptor that should be monitored for events.
 
239
The events can be either
 
240
.Va EV_READ ,
 
241
.Va EV_WRITE ,
 
242
or both,
 
243
indicating that an application can read or write from the file descriptor
 
244
respectively without blocking.
 
245
.Pp
 
246
The function
 
247
.Fa fn
 
248
will be called with the file descriptor that triggered the event and
 
249
the type of event which will be either
 
250
.Va EV_TIMEOUT ,
 
251
.Va EV_SIGNAL ,
 
252
.Va EV_READ ,
 
253
or
 
254
.Va EV_WRITE .
 
255
Additionally, an event which has registered interest in more than one of the
 
256
preceeding events, via bitwise-OR to
 
257
.Fn event_set ,
 
258
can provide its callback function with a bitwise-OR of more than one triggered
 
259
event.
 
260
The additional flag
 
261
.Va EV_PERSIST
 
262
makes an
 
263
.Fn event_add
 
264
persistent until
 
265
.Fn event_del
 
266
has been called.
 
267
.Pp
 
268
Once initialized, the
 
269
.Fa ev
 
270
structure can be used repeatedly with
 
271
.Fn event_add
 
272
and
 
273
.Fn event_del
 
274
and does not need to be reinitialized unless the function called and/or
 
275
the argument to it are to be changed.
 
276
However, when an
 
277
.Fa ev
 
278
structure has been added to libevent using
 
279
.Fn event_add
 
280
the structure must persist until the event occurs (assuming
 
281
.Fa EV_PERSIST
 
282
is not set) or is removed
 
283
using
 
284
.Fn event_del .
 
285
You may not reuse the same
 
286
.Fa ev
 
287
structure for multiple monitored descriptors; each descriptor
 
288
needs its own
 
289
.Fa ev .
 
290
.Pp
 
291
The function
 
292
.Fn event_add
 
293
schedules the execution of the
 
294
.Fa ev
 
295
event when the event specified in
 
296
.Fn event_set
 
297
occurs or in at least the time specified in the
 
298
.Fa tv .
 
299
If
 
300
.Fa tv
 
301
is
 
302
.Dv NULL ,
 
303
no timeout occurs and the function will only be called
 
304
if a matching event occurs on the file descriptor.
 
305
The event in the
 
306
.Fa ev
 
307
argument must be already initialized by
 
308
.Fn event_set
 
309
and may not be used in calls to
 
310
.Fn event_set
 
311
until it has timed out or been removed with
 
312
.Fn event_del .
 
313
If the event in the
 
314
.Fa ev
 
315
argument already has a scheduled timeout, the old timeout will be
 
316
replaced by the new one.
 
317
.Pp
 
318
The function
 
319
.Fn event_del
 
320
will cancel the event in the argument
 
321
.Fa ev .
 
322
If the event has already executed or has never been added
 
323
the call will have no effect.
 
324
.Pp
 
325
The functions
 
326
.Fn evtimer_set ,
 
327
.Fn evtimer_add ,
 
328
.Fn evtimer_del ,
 
329
.Fn evtimer_initialized ,
 
330
and
 
331
.Fn evtimer_pending
 
332
are abbreviations for common situations where only a timeout is required.
 
333
The file descriptor passed will be \-1, and the event type will be
 
334
.Va EV_TIMEOUT .
 
335
.Pp
 
336
The functions
 
337
.Fn signal_set ,
 
338
.Fn signal_add ,
 
339
.Fn signal_del ,
 
340
.Fn signal_initialized ,
 
341
and
 
342
.Fn signal_pending
 
343
are abbreviations.
 
344
The event type will be a persistent
 
345
.Va EV_SIGNAL .
 
346
That means
 
347
.Fn signal_set
 
348
adds
 
349
.Va EV_PERSIST .
 
350
.Pp
 
351
In order to avoid races in signal handlers, the
 
352
.Nm event
 
353
API provides two variables:
 
354
.Va event_sigcb
 
355
and
 
356
.Va event_gotsig .
 
357
A signal handler
 
358
sets
 
359
.Va event_gotsig
 
360
to indicate that a signal has been received.
 
361
The application sets
 
362
.Va event_sigcb
 
363
to a callback function.
 
364
After the signal handler sets
 
365
.Va event_gotsig ,
 
366
.Nm event_dispatch
 
367
will execute the callback function to process received signals.
 
368
The callback returns 1 when no events are registered any more.
 
369
It can return \-1 to indicate an error to the
 
370
.Nm event
 
371
library, causing
 
372
.Fn event_dispatch
 
373
to terminate with
 
374
.Va errno
 
375
set to
 
376
.Er EINTR .
 
377
.Pp
 
378
The function
 
379
.Fn event_once
 
380
is similar to
 
381
.Fn event_set .
 
382
However, it schedules a callback to be called exactly once and does not
 
383
require the caller to prepare an
 
384
.Fa event
 
385
structure.
 
386
This function supports
 
387
.Fa EV_TIMEOUT ,
 
388
.Fa EV_READ ,
 
389
and
 
390
.Fa EV_WRITE .
 
391
.Pp
 
392
The
 
393
.Fn event_pending
 
394
function can be used to check if the event specified by
 
395
.Fa event
 
396
is pending to run.
 
397
If
 
398
.Va EV_TIMEOUT
 
399
was specified and
 
400
.Fa tv
 
401
is not
 
402
.Dv NULL ,
 
403
the expiration time of the event will be returned in
 
404
.Fa tv .
 
405
.Pp
 
406
The
 
407
.Fn event_initialized
 
408
macro can be used to check if an event has been initialized.
 
409
.Pp
 
410
The
 
411
.Nm event_loop
 
412
function provides an interface for single pass execution of pending
 
413
events.
 
414
The flags
 
415
.Va EVLOOP_ONCE
 
416
and
 
417
.Va EVLOOP_NONBLOCK
 
418
are recognized.
 
419
The
 
420
.Nm event_loopexit
 
421
function exits from the event loop. The next
 
422
.Fn event_loop
 
423
iteration after the
 
424
given timer expires will complete normally (handling all queued events) then
 
425
exit without blocking for events again. Subsequent invocations of
 
426
.Fn event_loop
 
427
will proceed normally.
 
428
The
 
429
.Nm event_loopbreak
 
430
function exits from the event loop immediately.
 
431
.Fn event_loop
 
432
will abort after the next event is completed;
 
433
.Fn event_loopbreak
 
434
is typically invoked from this event's callback. This behavior is analogous
 
435
to the "break;" statement. Subsequent invocations of
 
436
.Fn event_loop
 
437
will proceed normally.
 
438
.Pp
 
439
It is the responsibility of the caller to provide these functions with
 
440
pre-allocated event structures.
 
441
.Pp
 
442
.Sh EVENT PRIORITIES
 
443
By default
 
444
.Nm libevent
 
445
schedules all active events with the same priority.
 
446
However, sometimes it is desirable to process some events with a higher
 
447
priority than others.
 
448
For that reason,
 
449
.Nm libevent
 
450
supports strict priority queues.
 
451
Active events with a lower priority are always processed before events
 
452
with a higher priority.
 
453
.Pp
 
454
The number of different priorities can be set initially with the
 
455
.Fn event_priority_init
 
456
function.
 
457
This function should be called before the first call to
 
458
.Fn event_dispatch .
 
459
The
 
460
.Fn event_priority_set
 
461
function can be used to assign a priority to an event.
 
462
By default,
 
463
.Nm libevent
 
464
assigns the middle priority to all events unless their priority
 
465
is explicitly set.
 
466
.Sh THREAD SAFE EVENTS
 
467
.Nm Libevent
 
468
has experimental support for thread-safe events.
 
469
When initializing the library via
 
470
.Fn event_init ,
 
471
an event base is returned.
 
472
This event base can be used in conjunction with calls to
 
473
.Fn event_base_set ,
 
474
.Fn event_base_dispatch ,
 
475
.Fn event_base_loop ,
 
476
.Fn event_base_loopexit ,
 
477
.Fn bufferevent_base_set
 
478
and
 
479
.Fn event_base_free .
 
480
.Fn event_base_set
 
481
should be called after preparing an event with
 
482
.Fn event_set ,
 
483
as
 
484
.Fn event_set
 
485
assigns the provided event to the most recently created event base.
 
486
.Fn bufferevent_base_set
 
487
should be called after preparing a bufferevent with
 
488
.Fn bufferevent_new .
 
489
.Fn event_base_free
 
490
should be used to free memory associated with the event base
 
491
when it is no longer needed.
 
492
.Sh BUFFERED EVENTS
 
493
.Nm libevent
 
494
provides an abstraction on top of the regular event callbacks.
 
495
This abstraction is called a
 
496
.Va "buffered event" .
 
497
A buffered event provides input and output buffers that get filled
 
498
and drained automatically.
 
499
The user of a buffered event no longer deals directly with the IO,
 
500
but instead is reading from input and writing to output buffers.
 
501
.Pp
 
502
A new bufferevent is created by
 
503
.Fn bufferevent_new .
 
504
The parameter
 
505
.Fa fd
 
506
specifies the file descriptor from which data is read and written to.
 
507
This file descriptor is not allowed to be a
 
508
.Xr pipe 2 .
 
509
The next three parameters are callbacks.
 
510
The read and write callback have the following form:
 
511
.Ft void
 
512
.Fn "(*cb)" "struct bufferevent *bufev" "void *arg" .
 
513
The error callback has the following form:
 
514
.Ft void
 
515
.Fn "(*cb)" "struct bufferevent *bufev" "short what" "void *arg" .
 
516
The argument is specified by the fourth parameter
 
517
.Fa "cbarg" .
 
518
A
 
519
.Fa bufferevent struct
 
520
pointer is returned on success, NULL on error.
 
521
Both the read and the write callback may be NULL.
 
522
The error callback has to be always provided.
 
523
.Pp
 
524
Once initialized, the bufferevent structure can be used repeatedly with
 
525
bufferevent_enable() and bufferevent_disable().
 
526
The flags parameter can be a combination of
 
527
.Va EV_READ
 
528
and
 
529
.Va EV_WRITE .
 
530
When read enabled the bufferevent will try to read from the file
 
531
descriptor and call the read callback.
 
532
The write callback is executed
 
533
whenever the output buffer is drained below the write low watermark,
 
534
which is
 
535
.Va 0
 
536
by default.
 
537
.Pp
 
538
The
 
539
.Fn bufferevent_write
 
540
function can be used to write data to the file descriptor.
 
541
The data is appended to the output buffer and written to the descriptor
 
542
automatically as it becomes available for writing.
 
543
.Fn bufferevent_write
 
544
returns 0 on success or \-1 on failure.
 
545
The
 
546
.Fn bufferevent_read
 
547
function is used to read data from the input buffer,
 
548
returning the amount of data read.
 
549
.Pp
 
550
If multiple bases are in use, bufferevent_base_set() must be called before
 
551
enabling the bufferevent for the first time.
 
552
.Sh NON-BLOCKING HTTP SUPPORT
 
553
.Nm libevent
 
554
provides a very thin HTTP layer that can be used both to host an HTTP
 
555
server and also to make HTTP requests.
 
556
An HTTP server can be created by calling
 
557
.Fn evhttp_new .
 
558
It can be bound to any port and address with the
 
559
.Fn evhttp_bind_socket
 
560
function.
 
561
When the HTTP server is no longer used, it can be freed via
 
562
.Fn evhttp_free .
 
563
.Pp
 
564
To be notified of HTTP requests, a user needs to register callbacks with the
 
565
HTTP server.
 
566
This can be done by calling
 
567
.Fn evhttp_set_cb .
 
568
The second argument is the URI for which a callback is being registered.
 
569
The corresponding callback will receive an
 
570
.Va struct evhttp_request
 
571
object that contains all information about the request.
 
572
.Pp
 
573
This section does not document all the possible function calls; please
 
574
check
 
575
.Va event.h
 
576
for the public interfaces.
 
577
.Sh ADDITIONAL NOTES
 
578
It is possible to disable support for
 
579
.Va epoll , kqueue , devpoll , poll
 
580
or
 
581
.Va select
 
582
by setting the environment variable
 
583
.Va EVENT_NOEPOLL , EVENT_NOKQUEUE , EVENT_NODEVPOLL , EVENT_NOPOLL
 
584
or
 
585
.Va EVENT_NOSELECT ,
 
586
respectively.
 
587
By setting the environment variable
 
588
.Va EVENT_SHOW_METHOD ,
 
589
.Nm libevent
 
590
displays the kernel notification method that it uses.
 
591
.Sh RETURN VALUES
 
592
Upon successful completion
 
593
.Fn event_add
 
594
and
 
595
.Fn event_del
 
596
return 0.
 
597
Otherwise, \-1 is returned and the global variable errno is
 
598
set to indicate the error.
 
599
.Sh SEE ALSO
 
600
.Xr kqueue 2 ,
 
601
.Xr poll 2 ,
 
602
.Xr select 2 ,
 
603
.Xr evdns 3 ,
 
604
.Xr timeout 9
 
605
.Sh HISTORY
 
606
The
 
607
.Nm event
 
608
API manpage is based on the
 
609
.Xr timeout 9
 
610
manpage by Artur Grabowski.
 
611
The port of
 
612
.Nm libevent
 
613
to Windows is due to Michael A. Davis.
 
614
Support for real-time signals is due to Taral.
 
615
.Sh AUTHORS
 
616
The
 
617
.Nm event
 
618
library was written by Niels Provos.
 
619
.Sh BUGS
 
620
This documentation is neither complete nor authoritative.
 
621
If you are in doubt about the usage of this API then
 
622
check the source code to find out how it works, write
 
623
up the missing piece of documentation and send it to
 
624
me for inclusion in this man page.