.\" man page for Munts Technologies Linux Simple I/O Library
.\"
.\" Copyright (C)2016-2023, Philip Munts dba Munts Technologies.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\" * Redistributions of source code must retain the above copyright notice,
.\"   this list of conditions and the following disclaimer.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH libevent 2 "21 December 2018" "version 1" "Linux Simple I/O Library"
.SH NAME
.B libevent
\-\- Linux Simple I/O Library: Event Notification Module
.SH SYNOPSIS
.nf
.B #include <libsimpleio/libevent.h>

.BI "void EVENT_open(int32_t *" epfd ", int32_t *" error ");"

.BI "void EVENT_close(int32_t " epfd ", int32_t *" error ");"

.BI "void EVENT_register_fd(int32_t " epfd ", int32_t " fd ", int32_t " events ","
.BI "  int32_t " handle ", int32_t *" error ");"

.BI "void EVENT_modify_fd(int32_t " epfd ", int32_t " fd ", int32_t " events ","
.BI "  int32_t " handle ", int32_t *" error ");"

.BI "void EVENT_unregister_fd(int32_t " epfd ", int32_t " fd ", int32_t *" error ");"

.BI "void EVENT_wait(int32_t " epfd ", int32_t *" fd ", int32_t *" event ","
.BI "  int32_t *" handle ", int32_t " timeoutms ", int32_t *" error ");"

.fi
Link with
.BR -lsimpleio .
.SH DESCRIPTION
.nh
All functions return either
.B 0
(upon success) or an
.B errno
value (upon failure) in
.IR *error .
.PP
.B EVENT_open()
must be called before any of the other functions, to open a connection to the
.B epoll
event notification subsystem.
.PP
.B EVENT_close()
must be called to close the connection to the
.B epoll
subsystem.
.PP
.B EVENT_register_fd()
registers the file descriptor
.I fd
for the event notifications selected by the
.IR events
parameter.  Event notification codes, such as
.B EPOLLIN
(input ready), are defined in
.BR /usr/include/sys/epoll.h ,
and may be
.BR OR "'d"
together to register for more than one type of event notification.
The
.I handle
parameter is passed in to the Linux kernel and will be passed back to
.B EVENT_wait()
when an event notification occurs.
.PP
.B EVENT_modify_fd()
modifies the event notifications enabled on a previously registered file descriptor.
The most common use case is to rearm a file descriptor registered with
.BR EPOLLONESHOT
for further event notifications.
After such a file descriptor has delivered an event, it will be disabled
from delivering any further event notifications until it is rearmed.
The
.I handle
parameter is passed in to the Linux kernel and will be passed back to
.B EVENT_wait()
when an event notification occurs.
.PP
.B EVENT_unregister_fd()
unregisters event notifications for the file descriptor
.IR fd .
.PP
.B EVENT_wait()
waits until an event notification occurs for any of the previously registered file descriptors.  The
.I timeoutms
parameter indicates the time in milliseconds to wait for an event notification.
A value of zero indicates
.B EVENT_wait()
should return immediately whether or not an event notification is available.
If an event notification occurs before the timeout expires,
.I *error
will be set to
.BR 0 ,
.I *fd
and
.I *event
will be set to the next available file descriptor and event notification code, and
.I *handle
will be set to whatever value was supplied to
.B EVENT_register_fd()
or
.BR EVENT_modify_fd() .
If no event notification occurs
before the timeout expires,
.I *error
will be set to
.B EAGAIN
and
.IR *fd ,
.IR *event ,
and
.IR *handle
will all be set to zero.  If some other error occurs,
.I *error will be set to an
.B errno
value and
.IR *fd ,
.IR *event ,
and
.IR *handle
will all be set to zero.
.SH SEE ALSO
.BR libsimpleio "(2), " libadc "(2), " libdac "(2), " libgpio "(2), " libhidraw "(2),"
.br
.BR libi2c "(2), " libipv4 "(2), " liblinux "(2), " liblinx "(2), " libpwm "(2),"
.br
.BR libserial "(2), " libspi "(2), " libstream "(2), " libwatchdog "(2)"
.SH AUTHOR
Philip Munts dba Munts Technologies.