From e3c1235880528190055241fa1872bbf68fbc1411 Mon Sep 17 00:00:00 2001 From: schwarze Date: Wed, 26 Apr 2023 18:56:16 +0000 Subject: [PATCH] New manual page written by Ted Bullock , to start working on it in the tree. --- lib/libevent/event_set.3 | 373 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 373 insertions(+) create mode 100644 lib/libevent/event_set.3 diff --git a/lib/libevent/event_set.3 b/lib/libevent/event_set.3 new file mode 100644 index 00000000000..6c95ec5ab3e --- /dev/null +++ b/lib/libevent/event_set.3 @@ -0,0 +1,373 @@ +.\" $OpenBSD: event_set.3,v 1.1 2023/04/26 18:56:16 schwarze Exp $ +.\" Copyright (c) 2023 Ted Bullock +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: April 26 2023 $ +.Dt EVENT_SET 3 +.Os +.Sh NAME +.Nm event_set , +.Nm evtimer_set , +.Nm signal_set , +.Nm event_base_set , +.Nm event_add , +.Nm evtimer_add , +.Nm signal_add , +.Nm event_del , +.Nm evtimer_del , +.Nm signal_del , +.Nm event_base_once , +.Nm event_once +.Nd configure an event +.Sh SYNOPSIS +.In event.h +.Ft void +.Fo event_set +.Fa "struct event *ev" +.Fa "int fd" +.Fa "short events" +.Fa "void (*fn)(int, short, void *)" +.Fa "void *arg" +.Fc +.Fd #define evtimer_set(ev, fn, arg) +.Fd #define signal_set(ev, signal, fn, arg) +.Ft int +.Fn event_base_set "struct event_base *base" "struct event *ev" +.Ft int +.Fn event_add "struct event *ev" "const struct timeval *tv" +.Fd #define evtimer_add(ev, tv) +.Fd #define signal_add(ev, tv) +.Ft int +.Fn event_del "struct event *ev" +.Fd #define evtimer_del(ev) +.Fd #define signal_del(ev) +.Ft int +.Fo event_base_once +.Fa "struct event_base *base" +.Fa "int fd" +.Fa "short events" +.Fa "void (*fn)(int, short, void *)" +.Fa "void *arg" +.Fa "const struct timeval *tv" +.Fc +.Ft int +.Fo event_once +.Fa "int fd" +.Fa "short events" +.Fa "void (*fn)(int, short, void *)" +.Fa "void *arg" +.Fa "const struct timeval *tv" +.Fc +.Sh DESCRIPTION +The +.Fn event_set +function prepares an +.Vt event +structure to monitor a file descriptor or signal. +Once prepared, the +.Vt event +can be scheduled using +.Fn event_add . +The event becomes activated and the callback is triggered when the file +descriptor state changes or timeout expires. +Refer to +.Xr event_base_loop 3 +for documentation on running an event loop. +.Pp +Arguments for +.Fn event_set +are as follows: +.Bl -tag -width 7n +.It Va ev : +A pointer to an +.Vt "event" +structure. +If +.Fa ev +is +.Dv NULL +the behavior is undefined. +.It Va fd : +The file descriptor or signal to monitor. +Unassociated timeout events require this set to \-1. +.It Va events : +Flags indicating how to monitor events. +Unassociated timeout events require this set to 0. +.Pp +.Bl -tag -width "EV_PERSIST:" -compact +.It Dv EV_READ : +Triggered when data is available for reading from the file descriptor. +.It Dv EV_WRITE : +Triggered when the file descriptor is ready for writing. +Can be combined with +.Dv EV_READ +to indicate that the program can read from or write to the file descriptor +without blocking. +.It Dv EV_SIGNAL : +Refers to a signal event that is triggered when a specified signal is +received. +Cannot be used together with either +.Dv EV_READ +or +.Dv EV_WRITE . +.It Dv EV_PERSIST : +Indicates that the event should persist after it triggers. +That is, it should remain active until it is removed by calling +.Fn event_del . +Signal events typically require this flag. +.El +.It Va fn : +A user-defined callback function that is executed when the event triggers. +.Pp +.Bl -enum -width Ds -compact +.It +The first parameter is the file descriptor or signal to monitor. +.It +The second parameter is an event flag composed of at least one of +.Dv EV_TIMEOUT , +.Dv EV_READ , +.Dv EV_WRITE , +.Dv EV_SIGNAL +and +.Dv EV_PERSIST +combined with a binary OR operation. +.It +The third parameter corresponds to a user-specified pointer passed as a +.Vt void * . +.El +.It Va arg : +User-specified pointer to pass to the callback function. +.El +.Pp +There are several helper macros that make it easier to set up timeout and +signal events in the library. +The helper macros share a distinct naming convention. +For example, the macros +.Fn evtimer_set +and +.Fn signal_set +are named consistently with the library function +.Fn event_set . +The following macro and function calls are equivalent: +.Bd -literal -offset indent +evtimer_set(ev, fn, arg); +event_set(ev, \-1, 0, fn, arg); +.Ed +.Pp +Likewise, configuring a signal event with +.Fn signal_set +has an equivalent call to +.Fn event_set : +.Bd -literal -offset indent +signal_set(ev, signal, fn, arg); +event_set(ev, signal, EV_SIGNAL|EV_PERSIST, fn, arg); +.Ed +.Pp +.Fn event_set +configures new events assuming that the library was initialized by +.Xr event_init 3 . +If a program needs to assign an event to a specific +.Vt event_base +structure, it should call +.Fn event_base_set +after calling +.Fn event_set . +The first argument of +.Fn event_base_set +is the target +.Vt event_base +structure, and the second argument is the +.Vt event +to be reassigned. +The behavior is undefined if either argument is +.Dv NULL . +Only events that have not been scheduled with +.Fn event_add +or corresponding helper macros or functions can be assigned to a new +.Vt event_base +structure. +.Pp +.Fn event_add +schedules events using the appropriate kernel notification method (see +.Xr event_base_new 3 +for information about kernel notification methods). +If a timeout is specified, it is added to the event timeout list. +Events can register as timeout events without attaching to file +descriptors or signals. +Programs can set the +.Fa tv +argument to +.Dv NULL +to specify that an event has no timeout. +The behavior is undefined if +.Fa ev +is +.Dv NULL . +The helper macros +.Fn evtimer_add +and +.Fn signal_add +correspond to +.Fn event_add . +.Pp +If +.Fn event_add +is called again with a new or updated timeout value before the event trigger +is processed, the function: +.Bl -enum +.It +Unschedules the existing timeout if it exists. +.It +Sets a new timeout starting from when the function was most recently invoked. +.It +Reschedules the event with the event loop. +.El +.Pp +.Fn event_del +removes an event from an event loop. +The +.Fa ev +argument is the event to remove. +The behavior of the function is undefined if +.Fa ev +is +.Dv NULL . +On success, it removes the event from internal event queues and unregisters it +with the kernel notification method. +The function fails if the library was not initialized with +.Xr event_init 3 +or the event was not previously assigned to an +.Vt event_base +with +.Fn event_base_set . +The function does not free memory assigned to user-defined data structures, +nor does it close open file descriptors. +The helper macros +.Fn evtimer_del +and +.Fn signal_del +correspond to +.Fn event_del . +.Pp +.Fn event_base_once +is used to schedule a callback function to be executed exactly once without +requiring the caller to create and manage an +.Vt event +structure. +The arguments are as follows: +.Bl -tag -width "events:" +.It Va base : +A pointer to an +.Vt event_base +structure initialized by +.Xr event_base_new 3 . +The behavior is undefined if +.Fa base +is +.Dv NULL . +.It Va fd : +A file descriptor to monitor. +.It Va events : +Flags matching +.Dv EV_TIMEOUT , +.Dv EV_READ +or +.Dv EV_WRITE . +.It Va fn : +A user-defined callback function that is executed when the event triggers. +This callback matches the same prototype and design used in +.Fn event_set . +.It Va arg : +A user-specified pointer to pass to the callback function. +.It Va tv : +A pointer to an optional timeout +.Vt timeval +structure, ignored if +.Dv NULL . +.El +.Pp +.Fn event_once +behaves similar to +.Fn event_base_once +and requires that the library is initialized with +.Xr event_init 3 . +.Pp +To check the status of a scheduled event, refer to the +.Xr event_pending 3 +manual page. +If a program needs to manually trigger an event, refer to +.Xr event_active 3 . +.Sh RETURN VALUES +These functions return 0 on success or \-1 on failure. +.Pp +.Fn event_base_set +returns \-1 if the event being reassigned has already +been processed by +.Fn event_add +or is not initialized. +.Pp +.Fn event_add +returns \-1 if a memory allocation fault occurs, +.Va errno +is set. +Other internal library errors terminate the program with +.Xr exit 3 +after reporting to the log callback (see +.Xr event_set_log_callback 3 ) . +.Sh ERRORS +On failure +.Fn event_add +can set errno +as follows: +.Bl -tag -width Er +.It Bq Er ENOMEM +System has insufficient memory to add the event to the event loop. +.El +.Sh SEE ALSO +.Xr event_active 3 , +.Xr event_base_loop 3 , +.Xr event_base_new 3 , +.Xr event_pending 3 +.Sh HISTORY +.Fn event_set , +.Fn event_add +and +.Fn event_del +first appeared in libevent-0.1 and have been available since +.Ox 3.2 . +.Pp +.Fn event_base_set +first appeared in libevent-1.0 and has been available since +.Ox 3.8 . +.Pp +.Fn event_once +first appeared in libevent-0.8 and has been available since +.Ox 3.8 . +.Pp +.Fn event_base_once +first appeared in libevent-1.3c and has been available since +.Ox 4.4 . +.Pp +The helper macros first appeared in libevent-0.6 and have been available since +.Ox 3.2 . +.Sh AUTHORS +.An -nosplit +.An Niels Provos +wrote the event library and these functions except for +.Fn event_base_once +which was also created by +.An Wouter Wijngaards . +.Pp +This manual page was written by +.An Ted Bullock Aq Mt tbullock@comlore.com . -- 2.20.1