New manual page written by Ted Bullock <tbullock at comlore dot com>,

to start working on it in the tree.

1 files changed, 373 insertions, 0 deletions

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 <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 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 .