mirror of
https://github.com/systemd/systemd.git
synced 2025-01-09 01:18:19 +03:00
man: add better descriptions of what event handlers do
The meaning of the return value, the default handlers, and loop exiting are now described.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
parent
ff97eb4aac
commit
9809a788e4
@ -114,25 +114,29 @@
|
||||
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>pid</parameter>
|
||||
parameter specifies the PID of the process to watch, which must be a direct child process of the invoking
|
||||
process. The <parameter>handler</parameter> must reference a function to call when the process changes
|
||||
state. The handler function will be passed the <parameter>userdata</parameter> pointer, which may be
|
||||
chosen freely by the caller. The handler also receives a pointer to a <structname>siginfo_t</structname>
|
||||
structure containing information about the child process event. The <parameter>options</parameter>
|
||||
parameter determines which state changes will be watched for. It must contain an OR-ed mask of
|
||||
<constant>WEXITED</constant> (watch for the child process terminating), <constant>WSTOPPED</constant>
|
||||
(watch for the child process being stopped by a signal), and <constant>WCONTINUED</constant> (watch for
|
||||
the child process being resumed by a signal). See <citerefentry
|
||||
project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
|
||||
further information.</para>
|
||||
process. The <parameter>options</parameter> parameter determines which state changes will be watched for.
|
||||
It must contain an OR-ed mask of <constant>WEXITED</constant> (watch for the child process terminating),
|
||||
<constant>WSTOPPED</constant> (watch for the child process being stopped by a signal), and
|
||||
<constant>WCONTINUED</constant> (watch for the child process being resumed by a signal). See
|
||||
<citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
||||
for further information.</para>
|
||||
|
||||
<para>Only a single handler may be installed for a specific
|
||||
child process. The handler is enabled for a single event
|
||||
(<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
|
||||
with
|
||||
<para>The <parameter>handler</parameter> must be a function to call when the process changes state or
|
||||
<constant>NULL</constant>. The handler function will be passed the <parameter>userdata</parameter>
|
||||
pointer, which may be chosen freely by the caller. The handler also receives a pointer to a
|
||||
<structname>siginfo_t</structname> structure containing information about the child process event. The
|
||||
handler may return negative to signal an error (see below), other return values are ignored. If
|
||||
<parameter>handler</parameter> is <constant>NULL</constant>, a default handler that calls
|
||||
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be
|
||||
used.</para>
|
||||
|
||||
<para>Only a single handler may be installed for a specific child process. The handler is enabled for a
|
||||
single event (<constant>SD_EVENT_ONESHOT</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.
|
||||
If the handler function returns a negative error code, it will either be disabled after the invocation,
|
||||
even if the <constant>SD_EVENT_ON</constant> mode was requested before, or it will cause the loop to
|
||||
terminate, see
|
||||
<citerefentry><refentrytitle>sd_event_source_set_exit_on_failure</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<para>To destroy an event source object use
|
||||
|
||||
@ -66,14 +66,17 @@
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>These three functions add new static event sources 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 event
|
||||
sources are enabled statically and will "fire" when the event loop
|
||||
is run and the conditions described below are met. The handler
|
||||
function will be passed the <parameter>userdata</parameter>
|
||||
pointer, which may be chosen freely by the caller.</para>
|
||||
<para>These three functions add new static event sources 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 event sources are enabled statically and will "fire" when
|
||||
the event loop is run and the conditions described below are met.</para>
|
||||
|
||||
<para>The <parameter>handler</parameter> is a function to call or <constant>NULL</constant>. The handler
|
||||
function will be passed the <parameter>userdata</parameter> pointer, which may be chosen freely by the
|
||||
caller. The handler may return negative to signal an error (see below), other return values are
|
||||
ignored. If <parameter>handler</parameter> is <constant>NULL</constant>, a default handler that calls
|
||||
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be
|
||||
used.</para>
|
||||
|
||||
<para><function>sd_event_add_defer()</function> adds a new event
|
||||
source that will be dispatched instantly, before the event loop
|
||||
@ -103,9 +106,11 @@
|
||||
(<constant>SD_EVENT_ON</constant>) or to make it fire just once
|
||||
(<constant>SD_EVENT_ONESHOT</constant>).</para>
|
||||
|
||||
<para>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.</para>
|
||||
<para>If the handler function returns a negative error code, it will either be disabled after the
|
||||
invocation, even if the <constant>SD_EVENT_ON</constant> mode was requested before, or it will cause the
|
||||
loop to terminate, see
|
||||
<citerefentry><refentrytitle>sd_event_source_set_exit_on_failure</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<para>To destroy an event source object use
|
||||
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
|
||||
@ -70,33 +70,40 @@
|
||||
<title>Description</title>
|
||||
|
||||
<para><function>sd_event_add_inotify()</function> adds a new <citerefentry
|
||||
project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> file system inode
|
||||
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>path</parameter>
|
||||
parameter specifies the path of the file system inode to watch. The <parameter>handler</parameter> must reference a
|
||||
function to call when the inode changes. The handler function will be passed the <parameter>userdata</parameter>
|
||||
pointer, which may be chosen freely by the caller. The handler also receives a pointer to a <structname>struct
|
||||
inotify_event</structname> structure containing information about the inode event. The <parameter>mask</parameter>
|
||||
parameter specifies which types of inode events to watch specifically. It must contain an OR-ed combination of
|
||||
<constant>IN_ACCESS</constant>, <constant>IN_ATTRIB</constant>, <constant>IN_CLOSE_WRITE</constant>, … flags. See
|
||||
<citerefentry project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
|
||||
project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> file
|
||||
system inode 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>path</parameter> parameter specifies the path of
|
||||
the file system inode to watch. The <parameter>mask</parameter> parameter specifies which types of inode
|
||||
events to watch specifically. It must contain an OR-ed combination of <constant>IN_ACCESS</constant>,
|
||||
<constant>IN_ATTRIB</constant>, <constant>IN_CLOSE_WRITE</constant>, … flags. See <citerefentry
|
||||
project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
|
||||
further information.</para>
|
||||
|
||||
<para>The <parameter>handler</parameter> must reference a function to call when the inode changes or
|
||||
<contant>NULL</contant>. The handler function will be passed the <parameter>userdata</parameter> pointer,
|
||||
which may be chosen freely by the caller. The handler also receives a pointer to a <structname>struct
|
||||
inotify_event</structname> structure containing information about the inode event. The handler may return
|
||||
negative to signal an error (see below), other return values are ignored. If
|
||||
<parameter>handler</parameter> is <constant>NULL</constant>, a default handler that calls
|
||||
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be
|
||||
used.</para>
|
||||
|
||||
<para><function>sd_event_add_inotify_fd()</function> is identical to
|
||||
<function>sd_event_add_inotify()</function>, except that it takes a file descriptor to an inode (possibly
|
||||
an <constant>O_PATH</constant> one, but any other will do too) instead of a path in the file
|
||||
system.</para>
|
||||
an <constant>O_PATH</constant> one, but any other will do too) instead of a path in the file system.
|
||||
</para>
|
||||
|
||||
<para>If multiple event sources are installed for the same inode the backing inotify watch descriptor is
|
||||
automatically shared. The mask parameter may contain any flag defined by the inotify API, with the exception of
|
||||
<constant>IN_MASK_ADD</constant>.</para>
|
||||
|
||||
<para>The handler is 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>. Alternatively,
|
||||
the <constant>IN_ONESHOT</constant> mask flag may be used to request <constant>SD_EVENT_ONESHOT</constant> mode.
|
||||
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.
|
||||
</para>
|
||||
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
Alternatively, the <constant>IN_ONESHOT</constant> mask flag may be used to request
|
||||
<constant>SD_EVENT_ONESHOT</constant> mode. 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.</para>
|
||||
|
||||
<para>As a special limitation the priority of inotify event sources may only be altered (see
|
||||
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
|
||||
|
||||
@ -115,27 +115,27 @@
|
||||
<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>
|
||||
for details.</para>
|
||||
|
||||
<para>By default, an event source will stay enabled
|
||||
continuously (<constant>SD_EVENT_ON</constant>), but this may be
|
||||
changed with
|
||||
<para>The <parameter>handler</parameter> is a function to call when the event source is triggered or
|
||||
<constant>NULL</constant>. 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>. The
|
||||
handler may return negative to signal an error (see below), other return values are ignored. If
|
||||
<parameter>handler</parameter> is <constant>NULL</constant>, a default handler that calls
|
||||
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be
|
||||
used.</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>
|
||||
If the handler function returns a negative error code, it will either be disabled after the invocation,
|
||||
even if the <constant>SD_EVENT_ON</constant> mode was requested before, or it will cause the loop to
|
||||
terminate, see
|
||||
<citerefentry><refentrytitle>sd_event_source_set_exit_on_failure</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
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
|
||||
|
||||
@ -64,16 +64,18 @@
|
||||
<parameter>source</parameter> parameter. The
|
||||
<parameter>signal</parameter> parameter specifies the numeric
|
||||
signal to be handled (see <citerefentry
|
||||
project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
|
||||
The <parameter>handler</parameter> parameter must reference a
|
||||
function to call when the signal is received or be
|
||||
<constant>NULL</constant>. The handler function will be passed
|
||||
the <parameter>userdata</parameter> pointer, which may be chosen
|
||||
freely by the caller. The handler also receives a pointer to a
|
||||
<structname>signalfd_siginfo</structname> structure containing
|
||||
information about the received signal. See <citerefentry
|
||||
project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
||||
for further information.</para>
|
||||
project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>).</para>
|
||||
|
||||
<para>The <parameter>handler</parameter> parameter is a function to call when the signal is received or
|
||||
<constant>NULL</constant>. The handler function will be passed the <parameter>userdata</parameter>
|
||||
pointer, which may be chosen freely by the caller. The handler also receives a pointer to a
|
||||
<structname>signalfd_siginfo</structname> structure containing information about the received signal. See
|
||||
<citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
||||
for further information. The handler may return negative to signal an error (see below), other return
|
||||
values are ignored. If <parameter>handler</parameter> is <constant>NULL</constant>, a default handler
|
||||
that calls
|
||||
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be
|
||||
used.</para>
|
||||
|
||||
<para>Only a single handler may be installed for a specific signal. The signal must be blocked in all
|
||||
threads before this function is called (using <citerefentry
|
||||
@ -84,9 +86,10 @@
|
||||
<para>By default, the event source is enabled permanently
|
||||
(<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.
|
||||
If the handler function returns a negative error code, it will either be disabled after the
|
||||
invocation, even if the <constant>SD_EVENT_ON</constant> mode was requested before, or it will cause the
|
||||
loop to terminate, see
|
||||
<citerefentry><refentrytitle>sd_event_source_set_exit_on_failure</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<para>To destroy an event source object use
|
||||
|
||||
@ -122,25 +122,30 @@
|
||||
timer event may be delayed. Use <constant>0</constant> to select the default accuracy (250ms). Use 1µs for maximum
|
||||
accuracy. Consider specifying 60000000µs (1min) or larger for long-running events that may be delayed
|
||||
substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively,
|
||||
improving power efficiency. The <parameter>handler</parameter> parameter shall reference a function to call when
|
||||
the timer elapses. The handler function will be passed the <parameter>userdata</parameter> pointer, which may be
|
||||
chosen freely by the caller. The handler is also passed the configured trigger time, even if it is actually called
|
||||
slightly later, subject to the specified accuracy value, the kernel timer slack (see
|
||||
<citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), and additional
|
||||
scheduling latencies. To query the actual time the handler was called use
|
||||
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
|
||||
improving power efficiency.</para>
|
||||
|
||||
<para>By default, the timer will elapse once
|
||||
(<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
|
||||
with
|
||||
<para>The <parameter>handler</parameter> is a function to call when the timer elapses or
|
||||
<constant>NULL</constant>. The <parameter>userdata</parameter> pointer will be passed to the handler
|
||||
function, and may be chosen freely by the caller. The configured trigger time is also passed to the
|
||||
handler, even if the call actually happens slightly later, subject to the specified accuracy value, the
|
||||
kernel timer slack (see
|
||||
<citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), and
|
||||
additional scheduling latencies. To query the actual time the handler was called use
|
||||
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
|
||||
handler may return negative to signal an error (see below), other return values are ignored. If
|
||||
<parameter>handler</parameter> is <constant>NULL</constant>, a default handler that calls
|
||||
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be
|
||||
used.</para>
|
||||
|
||||
<para>By default, the timer will elapse once (<constant>SD_EVENT_ONESHOT</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 a timer event set to <constant>SD_EVENT_ON</constant> will
|
||||
fire continuously unless its configured time is updated using
|
||||
<function>sd_event_source_set_time()</function>.
|
||||
</para>
|
||||
If the handler function returns a negative error code, it will either be disabled after the invocation,
|
||||
even if the <constant>SD_EVENT_ON</constant> mode was requested before, or it will cause the loop to
|
||||
terminate, see
|
||||
<citerefentry><refentrytitle>sd_event_source_set_exit_on_failure</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
Note that a timer event set to <constant>SD_EVENT_ON</constant> will fire continuously unless its
|
||||
configured time is updated using <function>sd_event_source_set_time()</function>.</para>
|
||||
|
||||
<para><function>sd_event_add_time_relative()</function> is like <function>sd_event_add_time()</function>,
|
||||
but takes a relative time specification. It's relative to the current time of the event loop iteration,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user