man: add better descriptions of what event handlers do

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

1 files changed, 16 insertions, 13 deletions

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