libevent

Section: Linux Simple I/O Library (2)
Updated: 21 December 2018
Index Return to Main Contents

NAME

libevent -- Linux Simple I/O Library: Event Notification Module

SYNOPSIS

#include <libsimpleio/libevent.h>

void EVENT_open(int32_t *epfd, int32_t *error);

void EVENT_close(int32_t epfd, int32_t *error);

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

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

void EVENT_unregister_fd(int32_t epfd, int32_t fd, int32_t *error);

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

Link with -lsimpleio.

DESCRIPTION

All functions return either 0 (upon success) or an errno value (upon failure) in *error.

EVENT_open() must be called before any of the other functions, to open a connection to the epoll event notification subsystem.

EVENT_close() must be called to close the connection to the epoll subsystem.

EVENT_register_fd() registers the file descriptor fd for the event notifications selected by the events parameter. Event notification codes, such as EPOLLIN (input ready), are defined in /usr/include/sys/epoll.h, and may be OR'd together to register for more than one type of event notification. The handle parameter is passed in to the Linux kernel and will be passed back to EVENT_wait() when an event notification occurs.

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 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 handle parameter is passed in to the Linux kernel and will be passed back to EVENT_wait() when an event notification occurs.

EVENT_unregister_fd() unregisters event notifications for the file descriptor fd.

EVENT_wait() waits until an event notification occurs for any of the previously registered file descriptors. The timeoutms parameter indicates the time in milliseconds to wait for an event notification. A value of zero indicates EVENT_wait() should return immediately whether or not an event notification is available. If an event notification occurs before the timeout expires, *error will be set to 0, *fd and *event will be set to the next available file descriptor and event notification code, and *handle will be set to whatever value was supplied to EVENT_register_fd() or EVENT_modify_fd(). If no event notification occurs before the timeout expires, *error will be set to EAGAIN and *fd, *event, and *handle will all be set to zero. If some other error occurs, *error will be set to an errno value and *fd, *event, and *handle will all be set to zero.

AUTHOR

Philip Munts dba Munts Technologies