man: add better descriptions of what event handlers do

The meaning of the return value, the default handlers, and loop exiting are now
described.

6 files changed, 121 insertions, 97 deletions

diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml
index 2961b3ee5e..621efad8d3 100644
--- a/man/sd_event_add_child.xml
+++ b/man/sd_event_add_child.xml
@@ -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>
-
-    <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
+    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>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
diff --git a/man/sd_event_add_defer.xml b/man/sd_event_add_defer.xml
index 54e8823000..e56e16a032 100644
--- a/man/sd_event_add_defer.xml
+++ b/man/sd_event_add_defer.xml
@@ -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>,
diff --git a/man/sd_event_add_inotify.xml b/man/sd_event_add_inotify.xml
index d632bf7282..e97fda25d7 100644
--- a/man/sd_event_add_inotify.xml
+++ b/man/sd_event_add_inotify.xml
@@ -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>)
diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml
index 323e57c79d..383a58a074 100644
--- a/man/sd_event_add_io.xml
+++ b/man/sd_event_add_io.xml
@@ -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>
-
-    <para>By default, an event source will stay enabled
-    continuously (<constant>SD_EVENT_ON</constant>), but this may be
-    changed with
+    for details.</para>
+
+    <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
diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml
index 1f0854f6cb..b2aaff87c1 100644
--- a/man/sd_event_add_signal.xml
+++ b/man/sd_event_add_signal.xml
@@ -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
diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml
index 3e8927f966..19f112b0f6 100644
--- a/man/sd_event_add_time.xml
+++ b/man/sd_event_add_time.xml
@@ -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>
-
-    <para>By default, the timer will elapse once
-    (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
-    with
+    improving power efficiency.</para>
+
+    <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,