'\" t
.TH "SD_EVENT_ADD_IO" "3" "" "systemd 241" "sd_event_add_io"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sd_event_add_io, sd_event_source_get_io_events, sd_event_source_set_io_events, sd_event_source_get_io_revents, sd_event_source_get_io_fd, sd_event_source_set_io_fd, sd_event_source_get_io_fd_own, sd_event_source_set_io_fd_own, sd_event_source, sd_event_io_handler_t \- Add an I/O event source to an event loop
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-event\&.h>
.fi
.ft
.sp
.ft B
.nf
typedef struct sd_event_source sd_event_source;
.fi
.ft
.HP \w'typedef\ int\ (*sd_event_io_handler_t)('u
.BI "typedef int (*sd_event_io_handler_t)(sd_event_source\ *" "s" ", int\ " "fd" ", uint32_t\ " "revents" ", void\ *" "userdata" ");"
.HP \w'int\ sd_event_add_io('u
.BI "int sd_event_add_io(sd_event\ *" "event" ", sd_event_source\ **" "source" ", int\ " "fd" ", uint32_t\ " "events" ", sd_event_io_handler_t\ " "handler" ", void\ *" "userdata" ");"
.HP \w'int\ sd_event_source_get_io_events('u
.BI "int sd_event_source_get_io_events(sd_event_source\ *" "source" ", uint32_t\ *" "events" ");"
.HP \w'int\ sd_event_source_set_io_events('u
.BI "int sd_event_source_set_io_events(sd_event_source\ *" "source" ", uint32_t\ " "events" ");"
.HP \w'int\ sd_event_source_get_io_revents('u
.BI "int sd_event_source_get_io_revents(sd_event_source\ *" "source" ", uint32_t\ *" "revents" ");"
.HP \w'int\ sd_event_source_get_io_fd('u
.BI "int sd_event_source_get_io_fd(sd_event_source\ *" "source" ");"
.HP \w'int\ sd_event_source_set_io_fd('u
.BI "int sd_event_source_set_io_fd(sd_event_source\ *" "source" ", int\ " "fd" ");"
.HP \w'int\ sd_event_source_get_io_fd_own('u
.BI "int sd_event_source_get_io_fd_own(sd_event_source\ *" "source" ");"
.HP \w'int\ sd_event_source_set_io_fd_own('u
.BI "int sd_event_source_set_io_fd_own(sd_event_source\ *" "source" ", int\ " "b" ");"
.SH "DESCRIPTION"
.PP
\fBsd_event_add_io()\fR
adds a new I/O event source to an event loop\&. The event loop object is specified in the
\fIevent\fR
parameter, the event source object is returned in the
\fIsource\fR
parameter\&. The
\fIfd\fR
parameter takes the UNIX file descriptor to watch, which may refer to a socket, a FIFO, a message queue, a serial connection, a character device, or any other file descriptor compatible with Linux
\fBepoll\fR(7)\&. The
\fIevents\fR
parameter takes a bit mask of events to watch for, a combination of the following event flags:
\fBEPOLLIN\fR,
\fBEPOLLOUT\fR,
\fBEPOLLRDHUP\fR,
\fBEPOLLPRI\fR, and
\fBEPOLLET\fR, see
\fBepoll_ctl\fR(2)
for details\&. The
\fIhandler\fR
shall reference a function to call when the event source is triggered\&. The
\fIuserdata\fR
pointer will be passed to the handler function, and may be chosen freely by the caller\&. The handler will also be passed the file descriptor the event was seen on, as well as the actual event flags\&. It\*(Aqs generally a subset of the events watched, however may additionally include
\fBEPOLLERR\fR
and
\fBEPOLLHUP\fR\&.
.PP
By default, an event source will stay enabled continuously (\fBSD_EVENT_ON\fR), but this may be changed with
\fBsd_event_source_set_enabled\fR(3)\&. If the handler function returns a negative error code, it will be disabled after the invocation, even if the
\fBSD_EVENT_ON\fR
mode was requested before\&. Note that an event source set to
\fBSD_EVENT_ON\fR
will fire continuously unless data is read from or written to the file descriptor to reset the mask of events seen\&.
.PP
Setting the I/O event mask to watch for to 0 does not mean that the event source won\*(Aqt be triggered anymore, as
\fBEPOLLHUP\fR
and
\fBEPOLLERR\fR
may be triggered even with a zero event mask\&. To temporarily disable an I/O event source use
\fBsd_event_source_set_enabled\fR(3)
with
\fBSD_EVENT_OFF\fR
instead\&.
.PP
To destroy an event source object use
\fBsd_event_source_unref\fR(3), but note that the event source is only removed from the event loop when all references to the event source are dropped\&. To make sure an event source does not fire anymore, even if it is still referenced, disable the event source using
\fBsd_event_source_set_enabled\fR(3)
with
\fBSD_EVENT_OFF\fR\&.
.PP
If the second parameter of
\fBsd_event_add_io()\fR
is
\fBNULL\fR
no reference to the event source object is returned\&. In this case the event source is considered "floating", and will be destroyed implicitly when the event loop itself is destroyed\&.
.PP
It is recommended to use
\fBsd_event_add_io()\fR
only in conjunction with file descriptors that have
\fBO_NONBLOCK\fR
set, to ensure that all I/O operations from invoked handlers are properly asynchronous and non\-blocking\&. Using file descriptors without
\fBO_NONBLOCK\fR
might result in unexpected starvation of other event sources\&. See
\fBfcntl\fR(2)
for details on enabling
\fBO_NONBLOCK\fR
mode\&.
.PP
\fBsd_event_source_get_io_events()\fR
retrieves the configured mask of watched I/O events of an event source created previously with
\fBsd_event_add_io()\fR\&. It takes the event source object and a pointer to a variable to store the mask in\&.
.PP
\fBsd_event_source_set_io_events()\fR
configures the mask of watched I/O events of an event source created previously with
\fBsd_event_add_io()\fR\&. It takes the event source object and the new event mask\&.
.PP
\fBsd_event_source_get_io_revents()\fR
retrieves the I/O event mask of currently seen but undispatched events from an event source created previously with
\fBsd_event_add_io()\fR\&. It takes the event source object and a pointer to a variable to store the event mask in\&. When called from a handler function on the handler\*(Aqs event source object this will return the same mask as passed to the handler\*(Aqs
\fIrevents\fR
parameter\&. This call is primarily useful to check for undispatched events of an event source from the handler of an unrelated (possibly higher priority) event source\&. Note the relation between
\fBsd_event_source_get_pending()\fR
and
\fBsd_event_source_get_io_revents()\fR: both functions will report non\-zero results when there\*(Aqs an event pending for the event source, but the former applies to all event source types, the latter only to I/O event sources\&.
.PP
\fBsd_event_source_get_io_fd()\fR
retrieves the UNIX file descriptor of an event source created previously with
\fBsd_event_add_io()\fR\&. It takes the event source object and returns the non\-negative file descriptor or a negative error number on error (see below)\&.
.PP
\fBsd_event_source_set_io_fd()\fR
changes the UNIX file descriptor of an I/O event source created previously with
\fBsd_event_add_io()\fR\&. It takes the event source object and the new file descriptor\&.
.PP
\fBsd_event_source_set_io_fd_own()\fR
controls whether the file descriptor of the event source shall be closed automatically when the event source is freed, i\&.e\&. whether it shall be considered \*(Aqowned\*(Aq by the event source object\&. By default it is not closed automatically, and the application has to do this on its own\&. The
\fIb\fR
parameter is a boolean parameter: if zero, the file descriptor is not closed automatically when the event source is freed, otherwise it is closed\&.
.PP
\fBsd_event_source_get_io_fd_own()\fR
may be used to query the current setting of the file descriptor ownership boolean flag as set with
\fBsd_event_source_set_io_fd_own()\fR\&. It returns positive if the file descriptor is closed automatically when the event source is destroyed, zero if not, and negative on error\&.
.SH "RETURN VALUE"
.PP
On success, these functions return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
.SH "ERRORS"
.PP
Returned values may indicate the following problems:
.PP
\fB\-ENOMEM\fR
.RS 4
Not enough memory to allocate an object\&.
.RE
.PP
\fB\-EINVAL\fR
.RS 4
An invalid argument has been passed\&.
.RE
.PP
\fB\-ESTALE\fR
.RS 4
The event loop is already terminated\&.
.RE
.PP
\fB\-ECHILD\fR
.RS 4
The event loop has been created in a different process\&.
.RE
.PP
\fB\-EDOM\fR
.RS 4
The passed event source is not an I/O event source\&.
.RE
.SH "NOTES"
.PP
These APIs are implemented as a shared library, which can be compiled and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsd-event\fR(3),
\fBsd_event_new\fR(3),
\fBsd_event_now\fR(3),
\fBsd_event_add_time\fR(3),
\fBsd_event_add_signal\fR(3),
\fBsd_event_add_child\fR(3),
\fBsd_event_add_inotify\fR(3),
\fBsd_event_add_defer\fR(3),
\fBsd_event_source_set_enabled\fR(3),
\fBsd_event_source_set_priority\fR(3),
\fBsd_event_source_set_userdata\fR(3),
\fBsd_event_source_set_description\fR(3),
\fBsd_event_source_get_pending\fR(3),
\fBepoll_ctl\fR(2),
\fBepoll\fR(7)