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, 86 insertions, 46 deletions

diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml
index 77bec4e706..d4b180cf03 100644
--- a/man/sd_event_add_child.xml
+++ b/man/sd_event_add_child.xml
@@ -21,7 +21,7 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
-<refentry id="sd_event_add_child">
+<refentry id="sd_event_add_child" xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_event_add_child</title>
@@ -45,13 +45,23 @@
   <refnamediv>
     <refname>sd_event_add_child</refname>
     <refname>sd_event_source_get_child_pid</refname>
+    <refname>sd_event_child_handler_t</refname>
 
-    <refpurpose>Add a child state change event source to an event loop</refpurpose>
+    <refpurpose>Add a child process state change 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_child_handler_t</function>)</funcdef>
+        <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
+        <paramdef>const siginfo_t *<parameter>si</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+      </funcprototype>
 
       <funcprototype>
         <funcdef>int <function>sd_event_add_child</function></funcdef>
@@ -64,13 +74,6 @@
       </funcprototype>
 
       <funcprototype>
-        <funcdef>typedef int (*<function>sd_event_child_handler_t</function>)</funcdef>
-        <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
-        <paramdef>const siginfo_t *<parameter>si</parameter></paramdef>
-        <paramdef>void *<parameter>userdata</parameter></paramdef>
-      </funcprototype>
-
-      <funcprototype>
         <funcdef>int <function>sd_event_source_get_child_pid</function></funcdef>
         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
         <paramdef>pid_t *<parameter>pid</parameter></paramdef>
@@ -83,42 +86,75 @@
     <title>Description</title>
 
     <para><function>sd_event_add_child()</function> adds a new child
-    state change event source to an event loop object. The event loop
-    is specified in <parameter>event</parameter>, the event source is
-    returned in the <parameter>source</parameter> parameter. The
-    <parameter>pid</parameter> parameter specifies the process to
-    watch. 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>const
-    siginfo_t</structname> structure containing the information about
-    the 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 state change 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>pid</parameter> parameter specifies the PID of the
+    process to watch. 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
-    being stopped by a signal), and <constant>WCONTINUED</constant>
-    (watch for the child being resumed by a signal). See
-    <citerefentry><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    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. The handler is enabled
-    for a single event (<constant>SD_EVENT_ONESHOT</constant>),
-    but this may be
-    changed with
+    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
-    <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_child()</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>Note that the <parameter>handler</parameter> function is
+    invoked at a time where the child process is not reaped yet (and
+    thus still is exposed as a zombie process by the kernel). However,
+    the child will be reaped automatically after the function
+    returns. Child processes for which no child process state change
+    event sources are installed will not be reaped by the event loop
+    implementation.</para>
+
+    <para>If both a child process state change event source and a
+    <constant>SIGCHLD</constant> signal event source is installed in
+    the same event loop, the configured event source priorities decide
+    which event source is dispatched first. If the signal handler is
+    processed first, it should leave the child processes for which
+    child process state change event sources are installed unreaped.</para>
+
     <para><function>sd_event_source_get_child_pid()</function>
-    retrieves the configured <parameter>pid</parameter> of a child
-    state change event source created previously with
+    retrieves the configured PID of a child process state change event
+    source created previously with
     <function>sd_event_add_child()</function>. It takes the event
     source object as the <parameter>source</parameter> parameter and a
-    pointer to <type>pid_t</type> to return the result in.
+    pointer to a <type>pid_t</type> variable to return the process ID
+    in.
     </para>
   </refsect1>
 
@@ -158,7 +194,7 @@
         <term><constant>-EBUSY</constant></term>
 
         <listitem><para>A handler is already installed for this
-        child.</para></listitem>
+        child process.</para></listitem>
 
       </varlistentry>
 
@@ -176,19 +212,17 @@
 
       </varlistentry>
 
-    </variablelist>
-  </refsect1>
+      <varlistentry>
+        <term><constant>-EDOM</constant></term>
 
-  <refsect1>
-    <title>Notes</title>
+        <listitem><para>The passed event source is not a child process event source.</para></listitem>
+      </varlistentry>
 
-    <para><function>sd_event_add_child()</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>
 
@@ -196,10 +230,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_signal</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_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 project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
     </para>
   </refsect1>