mirror of
https://github.com/systemd/systemd.git
synced 2024-12-23 21:35:11 +03:00
0bca283127
Let's make sure we get back to 100% man page documentation coverage of our sd-event APIs. We are bad enough at the others, let's get these ones right at least.
306 lines
15 KiB
XML
306 lines
15 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
|
|
|
|
<refentry id="sd_event_add_io" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>sd_event_add_io</title>
|
|
<productname>systemd</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>sd_event_add_io</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>sd_event_add_io</refname>
|
|
<refname>sd_event_source_get_io_events</refname>
|
|
<refname>sd_event_source_set_io_events</refname>
|
|
<refname>sd_event_source_get_io_revents</refname>
|
|
<refname>sd_event_source_get_io_fd</refname>
|
|
<refname>sd_event_source_set_io_fd</refname>
|
|
<refname>sd_event_source_get_io_fd_own</refname>
|
|
<refname>sd_event_source_set_io_fd_own</refname>
|
|
<refname>sd_event_source</refname>
|
|
<refname>sd_event_io_handler_t</refname>
|
|
|
|
<refpurpose>Add an I/O event source to an event loop</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
|
|
|
|
<funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
|
|
|
|
<funcprototype>
|
|
<funcdef>typedef int (*<function>sd_event_io_handler_t</function>)</funcdef>
|
|
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
|
|
<paramdef>int <parameter>fd</parameter></paramdef>
|
|
<paramdef>uint32_t <parameter>revents</parameter></paramdef>
|
|
<paramdef>void *<parameter>userdata</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_event_add_io</function></funcdef>
|
|
<paramdef>sd_event *<parameter>event</parameter></paramdef>
|
|
<paramdef>sd_event_source **<parameter>source</parameter></paramdef>
|
|
<paramdef>int <parameter>fd</parameter></paramdef>
|
|
<paramdef>uint32_t <parameter>events</parameter></paramdef>
|
|
<paramdef>sd_event_io_handler_t <parameter>handler</parameter></paramdef>
|
|
<paramdef>void *<parameter>userdata</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_event_source_get_io_events</function></funcdef>
|
|
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
|
|
<paramdef>uint32_t *<parameter>events</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_event_source_set_io_events</function></funcdef>
|
|
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
|
|
<paramdef>uint32_t <parameter>events</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_event_source_get_io_revents</function></funcdef>
|
|
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
|
|
<paramdef>uint32_t *<parameter>revents</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_event_source_get_io_fd</function></funcdef>
|
|
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_event_source_set_io_fd</function></funcdef>
|
|
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
|
|
<paramdef>int <parameter>fd</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_event_source_get_io_fd_own</function></funcdef>
|
|
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_event_source_set_io_fd_own</function></funcdef>
|
|
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
|
|
<paramdef>int <parameter>b</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><function>sd_event_add_io()</function> adds a new I/O event
|
|
source to an event loop. The event loop object is specified in the
|
|
<parameter>event</parameter> parameter, the event source object is
|
|
returned in the <parameter>source</parameter> parameter. The
|
|
<parameter>fd</parameter> 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
|
|
<citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
|
|
<parameter>events</parameter> parameter takes a bit mask of events
|
|
to watch for, a combination of the following event flags:
|
|
<constant>EPOLLIN</constant>, <constant>EPOLLOUT</constant>,
|
|
<constant>EPOLLRDHUP</constant>, <constant>EPOLLPRI</constant>,
|
|
and <constant>EPOLLET</constant>, see
|
|
<citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
|
for details. The <parameter>handler</parameter> shall reference a
|
|
function to call when the event source is triggered. The
|
|
<parameter>userdata</parameter> 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's generally a subset of
|
|
the events watched, however may additionally include
|
|
<constant>EPOLLERR</constant> and <constant>EPOLLHUP</constant>.
|
|
</para>
|
|
|
|
<para>By default, an event source will stay enabled
|
|
continuously (<constant>SD_EVENT_ON</constant>), but this may be
|
|
changed with
|
|
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
|
If the handler function returns a negative error code, it will be
|
|
disabled after the invocation, even if the
|
|
<constant>SD_EVENT_ON</constant> mode was requested before. Note
|
|
that an event source set to <constant>SD_EVENT_ON</constant> will
|
|
fire continuously unless data is read from or written to the file
|
|
descriptor to reset the mask of events seen.
|
|
</para>
|
|
|
|
<para>Setting the I/O event mask to watch for to 0 does not mean
|
|
that the event source won't be triggered anymore, as
|
|
<constant>EPOLLHUP</constant> and <constant>EPOLLERR</constant>
|
|
may be triggered even with a zero event mask. To temporarily
|
|
disable an I/O event source use
|
|
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
with <constant>SD_EVENT_OFF</constant> instead.</para>
|
|
|
|
<para>To destroy an event source object use
|
|
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
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
|
|
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
with <constant>SD_EVENT_OFF</constant>.</para>
|
|
|
|
<para>If the second parameter of
|
|
<function>sd_event_add_io()</function> is
|
|
<constant>NULL</constant> 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.</para>
|
|
|
|
<para>Note that this call does not take possession of the file descriptor passed in, ownership (and thus
|
|
the duty to close it when it is no longer needed) remains with the caller. However, with the
|
|
<function>sd_event_source_set_io_fd_own()</function> call (see below) the event source may optionally
|
|
take ownership of the file descriptor after the event source has been created. In that case the file
|
|
descriptor is closed automatically as soon as the event source is released.</para>
|
|
|
|
<para>It is recommended to use
|
|
<function>sd_event_add_io()</function> only in conjunction with
|
|
file descriptors that have <constant>O_NONBLOCK</constant> set, to
|
|
ensure that all I/O operations from invoked handlers are properly
|
|
asynchronous and non-blocking. Using file descriptors without
|
|
<constant>O_NONBLOCK</constant> might result in unexpected
|
|
starvation of other event sources. See
|
|
<citerefentry project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
|
for details on enabling <constant>O_NONBLOCK</constant> mode.</para>
|
|
|
|
<para><function>sd_event_source_get_io_events()</function> retrieves
|
|
the configured mask of watched I/O events of an event source created
|
|
previously with <function>sd_event_add_io()</function>. It takes
|
|
the event source object and a pointer to a variable to store the
|
|
mask in.</para>
|
|
|
|
<para><function>sd_event_source_set_io_events()</function>
|
|
configures the mask of watched I/O events of an event source created
|
|
previously with <function>sd_event_add_io()</function>. It takes the
|
|
event source object and the new event mask.</para>
|
|
|
|
<para><function>sd_event_source_get_io_revents()</function>
|
|
retrieves the I/O event mask of currently seen but undispatched
|
|
events from an event source created previously with
|
|
<function>sd_event_add_io()</function>. 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's event
|
|
source object this will return the same mask as passed to the
|
|
handler's <parameter>revents</parameter> 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
|
|
<function>sd_event_source_get_pending()</function> and
|
|
<function>sd_event_source_get_io_revents()</function>: both
|
|
functions will report non-zero results when there's an event
|
|
pending for the event source, but the former applies to all event
|
|
source types, the latter only to I/O event sources.</para>
|
|
|
|
<para><function>sd_event_source_get_io_fd()</function> retrieves
|
|
the UNIX file descriptor of an event source created previously
|
|
with <function>sd_event_add_io()</function>. It takes the event
|
|
source object and returns the non-negative file descriptor
|
|
or a negative error number on error (see below).</para>
|
|
|
|
<para><function>sd_event_source_set_io_fd()</function>
|
|
changes the UNIX file descriptor of an I/O event source created
|
|
previously with <function>sd_event_add_io()</function>. It takes
|
|
the event source object and the new file descriptor.</para>
|
|
|
|
<para><function>sd_event_source_set_io_fd_own()</function> 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 'owned' by the
|
|
event source object. By default it is not closed automatically, and the application has to do this on its own. The
|
|
<parameter>b</parameter> parameter is a boolean parameter: if zero, the file descriptor is not closed automatically
|
|
when the event source is freed, otherwise it is closed.</para>
|
|
|
|
<para><function>sd_event_source_get_io_fd_own()</function> may be used to query the current setting of the file
|
|
descriptor ownership boolean flag as set with <function>sd_event_source_set_io_fd_own()</function>. It returns
|
|
positive if the file descriptor is closed automatically when the event source is destroyed, zero if not, and
|
|
negative on error.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>On success, these functions return 0 or a positive
|
|
integer. On failure, they return a negative errno-style error
|
|
code.</para>
|
|
|
|
<refsect2>
|
|
<title>Errors</title>
|
|
|
|
<para>Returned values may indicate the following problems:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><constant>-ENOMEM</constant></term>
|
|
|
|
<listitem><para>Not enough memory to allocate an object.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><constant>-EINVAL</constant></term>
|
|
|
|
<listitem><para>An invalid argument has been passed.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><constant>-ESTALE</constant></term>
|
|
|
|
<listitem><para>The event loop is already terminated.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><constant>-ECHILD</constant></term>
|
|
|
|
<listitem><para>The event loop has been created in a different process.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><constant>-EDOM</constant></term>
|
|
|
|
<listitem><para>The passed event source is not an I/O event source.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<xi:include href="libsystemd-pkgconfig.xml" />
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_source_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
|
|
<citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|