man: fully document sd-event interfaces

This completes the set of man pages for sd-event and contains some minor
other fixes for other man pages too.

The sd_event_set_name(3) man page is renamed to
sd_event_source_set_description(3), which is the correct name of the
concept today.

1 files changed, 73 insertions, 45 deletions

diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml
index 0923fe0ae7..b5312735d2 100644
--- a/man/sd_event_add_signal.xml
+++ b/man/sd_event_add_signal.xml
@@ -21,7 +21,7 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
-<refentry id="sd_event_add_signal">
+<refentry id="sd_event_add_signal" xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_event_add_signal</title>
@@ -45,13 +45,24 @@
   <refnamediv>
     <refname>sd_event_add_signal</refname>
     <refname>sd_event_source_get_signal</refname>
+    <refname>sd_event_signal_handler_t</refname>
 
-    <refpurpose>Add a signal event source to an event loop</refpurpose>
+    <refpurpose>Add a UNIX process signal event source to an event
+    loop</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
     <funcsynopsis>
-      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+      <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef>
+        <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
+        <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+      </funcprototype>
 
       <funcprototype>
         <funcdef>int <function>sd_event_add_signal</function></funcdef>
@@ -63,13 +74,6 @@
       </funcprototype>
 
       <funcprototype>
-        <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef>
-        <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
-        <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef>
-        <paramdef>void *<parameter>userdata</parameter></paramdef>
-      </funcprototype>
-
-      <funcprototype>
         <funcdef>int <function>sd_event_source_get_signal</function></funcdef>
         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
       </funcprototype>
@@ -80,41 +84,61 @@
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_event_add_signal()</function> adds a new signal
-    event source to an event loop object. The event loop is specified
-    in <parameter>event</parameter>, and the event source is returned in
-    the <parameter>source</parameter> parameter. The
-    <parameter>signal</parameter> parameter specifies the signal to be handled
-    (see
-    <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
-    The <parameter>handler</parameter> must reference a function to
-    call when the signal is delivered or be <constant>NULL</constant>.
-    The handler function will be passed the
-    <parameter>userdata</parameter> pointer, which may be chosen
+    <para><function>sd_event_add_signal()</function> adds a new UNIX
+    process signal event source to an event loop. The event loop
+    object is specified in the <parameter>event</parameter> parameter,
+    and the event source object is returned in the
+    <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>const struct signalfd_siginfo</structname> containing
-    the information about the received signal. See
-    <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    <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>
 
     <para>Only a single handler may be installed for a specific
-    signal. The signal will be unblocked, and must be
-    blocked when the function is called. If the handler is not
-    specified (<parameter>handler</parameter> is
+    signal. The signal will be unblocked by this call, and must be
+    blocked before this function is called in all threads (using
+    <citerefentry
+    project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry>). If
+    the handler is not specified (<parameter>handler</parameter> is
     <constant>NULL</constant>), a default handler which causes the
-    program to exit will be used.  By default, the handler is enabled
-    permanently (<constant>SD_EVENT_ON</constant>), but this may be
-    changed with
+    program to exit cleanly will be used.</para>
+
+    <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
-    <constant>SD_EVENT_ON</constant> mode is set.
+    disabled after the invocation, even if the
+    <constant>SD_EVENT_ON</constant> mode was requested before.
     </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 when there's still a
+    reference to it kept, consider setting the event source to
+    <constant>SD_EVENT_OFF</constant> with
+    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+    <para>If the the second parameter of
+    <function>sd_event_add_signal()</function> is passed as NULL 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><function>sd_event_source_get_signal()</function> retrieves
-    the configured signal number of a signal event source created
-    previously with <function>sd_event_add_signal()</function>. It
-    takes the event source object as the <parameter>source</parameter>
+    the configured UNIX process signal number of a signal event source
+    created previously with
+    <function>sd_event_add_signal()</function>. It takes the event
+    source object as the <parameter>source</parameter>
     parameter.</para>
 
   </refsect1>
@@ -168,19 +192,17 @@
 
       </varlistentry>
 
-    </variablelist>
-  </refsect1>
+      <varlistentry>
+        <term><constant>-EDOM</constant></term>
 
-  <refsect1>
-    <title>Notes</title>
+        <listitem><para>The passed event source is not a signal event source.</para></listitem>
+      </varlistentry>
 
-    <para><function>sd_event_add_signal()</function> and the other functions
-    described here are available as a shared library, which can be
-    compiled and linked to with the
-    <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    file.</para>
+    </variablelist>
   </refsect1>
 
+  <xi:include href="libsystemd-pkgconfig.xml" />
+
   <refsect1>
     <title>See Also</title>
 
@@ -188,10 +210,16 @@
       <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_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_event_add_child</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_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
     </para>
   </refsect1>