.\" $OpenBSD: event_set.3,v 1.2 2023/04/27 15:44:36 schwarze Exp $
.\" Copyright (c) 2023 Ted Bullock <tbullock@comore.com>
.\"
.\" 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 27 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 (*callback)(int, short, void *)"
.Fa "void *arg"
.Fc
.Fd #define evtimer_set(ev, callback, arg)
.Fd #define signal_set(ev, signal, callback, 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 (*callback)(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 (*callback)(int, short, void *)"
.Fa "void *arg"
.Fa "const struct timeval *tv"
.Fc
.Sh DESCRIPTION
The
.Fn event_set
function initializes an uninitialized, unused,
.Vt event
structure to monitor a file descriptor, signal, or timeout.
Once initialized, the
.Vt event
can be scheduled using
.Fn event_add .
The event becomes activated and the
.Fa callback
is triggered when the file descriptor state changes, the signal arrives,
or the 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 callback :
A user-defined 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
.Fa 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, callback, arg);
event_set(ev, \-1, 0, callback, 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, callback, arg);
event_set(ev, signal, EV_SIGNAL|EV_PERSIST, callback, arg);
.Ed
.Pp
If
.Xr event_init 3
was called earlier,
.Fn event_set
associates
.Fa ev
with the
.Vt event_base
structure it created; otherwise,
.Fa ev
is not associated with any
.Vt event_base
structure.
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 the
.Fa ev
using the kernel notification method of its associated
.Vt event_base
structure; 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
or uninitialized.
The effect of the macros
.Fn evtimer_add
and
.Fn signal_add
is identical 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 the event loop of its associated
.Vt event_base
structure.
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
and 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 effect of the macros
.Fn evtimer_del
and
.Fn signal_del
is identical to
.Fn event_del .
.Pp
.Fn event_base_once
is used to schedule a
.Fa 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 :
.Dv EV_TIMEOUT ,
.Dv EV_READ ,
.Dv EV_WRITE ,
or
.Dv EV_READ | EV_WRITE .
.It Va callback :
A user-defined 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
.Fa 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 .
.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,
.Fn signal_set ,
.Fn signal_add ,
and
.Fn signal_del
in libevent-0.5 ,
and
.Fn evtimer_set ,
.Fn evtimer_add
and
.Fn evtimer_del
in libevent-0.6.
These functions have been available since
.Ox 3.2 .
.Pp
.Fn event_once
first appeared in libevent-0.8 and has been available since
.Ox 3.6 .
.Pp
.Fn event_base_set
first appeared in libevent-1.0 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 .
.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 .