man: document the new sd-event pidfd magic

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 20c3d09da08ec8b0dd643764d1b543799007be48..0f6897a080bcb951dac8a8a91a7f65d4ef84ce2b 100644 (file)
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -371,7 +371,15 @@ manpages = [
  ['sd_bus_wait', '3', [], ''],
  ['sd_event_add_child',
   '3',
-  ['sd_event_child_handler_t', 'sd_event_source_get_child_pid'],
+  ['sd_event_add_child_pidfd',
+   'sd_event_child_handler_t',
+   'sd_event_source_get_child_pid',
+   'sd_event_source_get_child_pidfd',
+   'sd_event_source_get_child_pidfd_own',
+   'sd_event_source_get_child_process_own',
+   'sd_event_source_send_child_signal',
+   'sd_event_source_set_child_pidfd_own',
+   'sd_event_source_set_child_process_own'],
   ''],
  ['sd_event_add_defer',
   '3',

diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml
index c146e3121ba4427cdc008f03cb965d3b34f8284d..1db536ff2ad133a5021626d7c483533c99aa9cfb 100644 (file)
--- a/man/sd_event_add_child.xml
+++ b/man/sd_event_add_child.xml
@@ -17,7 +17,14 @@
 
   <refnamediv>
     <refname>sd_event_add_child</refname>
+    <refname>sd_event_add_child_pidfd</refname>
     <refname>sd_event_source_get_child_pid</refname>
+    <refname>sd_event_source_get_child_pidfd</refname>
+    <refname>sd_event_source_get_child_pidfd_own</refname>
+    <refname>sd_event_source_set_child_pidfd_own</refname>
+    <refname>sd_event_source_get_child_process_own</refname>
+    <refname>sd_event_source_set_child_process_own</refname>
+    <refname>sd_event_source_send_child_signal</refname>
     <refname>sd_event_child_handler_t</refname>
 
     <refpurpose>Add a child process state change event source to an event loop</refpurpose>
@@ -46,40 +53,77 @@
         <paramdef>void *<parameter>userdata</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_event_add_child_pidfd</function></funcdef>
+        <paramdef>sd_event *<parameter>event</parameter></paramdef>
+        <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
+        <paramdef>int <parameter>pidfd</parameter></paramdef>
+        <paramdef>int <parameter>options</parameter></paramdef>
+        <paramdef>sd_event_child_handler_t <parameter>handler</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>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_get_child_pidfd</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_get_child_pidfd_own</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_set_child_pidfd_own</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>int <parameter>own</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_get_child_process_own</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_set_child_process_own</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>int <parameter>own</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_send_child_signal</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>int <parameter>sig</parameter></paramdef>
+        <paramdef>const siginfo_t *<parameter>info</parameter></paramdef>
+        <paramdef>unsigned <parameter>flags</parameter></paramdef>
+      </funcprototype>
+
     </funcsynopsis>
   </refsynopsisdiv>
 
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_event_add_child()</function> adds a new 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
-    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><function>sd_event_add_child()</function> adds a new 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, 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
@@ -127,6 +171,17 @@
     processed first, it should leave the child processes for which
     child process state change event sources are installed unreaped.</para>
 
+    <para><function>sd_event_add_child_pidfd()</function> is similar to
+    <function>sd_event_add_child()</function> but takes a file descriptor referencing the process ("pidfd")
+    instead of the numeric PID. A suitable file descriptor may be acquired via <citerefentry
+    project='man-pages'><refentrytitle>pidfd_open</refentrytitle><manvolnum>2</manvolnum></citerefentry> and
+    related calls. The passed file descriptor is not closed when the event source is freed again, unless
+    <function>sd_event_source_set_child_pidfd_own()</function> is used to turn this behaviour on. Note that
+    regardless which of <function>sd_event_add_child()</function> and
+    <function>sd_event_add_child_pidfd()</function> is used for allocating an event source, the watched
+    process has to be a direct child process of the invoking process. Also in both cases
+    <constant>SIGCHLD</constant> has to be blocked in the invoking process.</para>
+
     <para><function>sd_event_source_get_child_pid()</function>
     retrieves the configured PID of a child process state change event
     source created previously with
@@ -135,6 +190,45 @@
     pointer to a <type>pid_t</type> variable to return the process ID
     in.
     </para>
+
+    <para><function>sd_event_source_get_child_pidfd()</function> retrieves the file descriptor referencing
+    the watched process ("pidfd") if this functionality is available. On kernels that support the concept the
+    event loop will make use of pidfds to watch child processes, regardless if the individual event sources
+    are allocated via <function>sd_event_add_child()</function> or
+    <function>sd_event_add_child_pidfd()</function>. If the latter call was used to allocate the event
+    source, this function returns the file descriptor used for allocation. On kernels that do not support the
+    pidfd concept this function will fail with <constant>EOPNOTSUPP</constant>. This call takes the event
+    source object as the <parameter>source</parameter> parameter and returns the numeric file descriptor.
+    </para>
+
+    <para><function>sd_event_source_get_child_pidfd_own()</function> may be used to query whether the pidfd
+    the event source encapsulates shall be closed when the event source is freed. This function returns zero
+    if the pidfd shall be left open, and positive if it shall be closed automatically. By default this
+    setting defaults to on if the event source was allocated via <function>sd_event_add_child()</function>
+    and off if it was allocated via <function>sd_event_add_child_pidfd()</function>. The
+    <function>sd_event_source_set_child_pidfd_own()</function> function may be used to change the setting and
+    takes a boolean parameter with the new setting.</para>
+
+    <para><function>sd_event_source_get_child_process_own()</function> may be used to query whether the
+    process the event source watches shall be killed (with <constant>SIGKILL</constant>) and reaped when the
+    event source is freed. This function returns zero if the process shell be left running, and positive if
+    it shall be killed and reaped automatically. By default this setting defaults to off. The
+    <function>sd_event_source_set_child_process_own()</function> function may be used to change the setting
+    and takes a boolean parameter with the new setting. Note that currently if the calling process is
+    terminated abnormally the watched process might survive even thought the event source ceases to
+    exist. This behaviour might change eventually.</para>
+
+    <para><function>sd_event_source_send_child_signal()</function> may be used to send a UNIX signal to the
+    watched process. If the pidfd concept is supported in the kernel, this is implemented via <citerefentry
+    project='man-pages'><refentrytitle>pidfd_send_signal</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    and otherwise via <citerefentry
+    project='man-pages'><refentrytitle>rt_sigqueueinfo</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    (or via <citerefentry
+    project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry> in case
+    <parameter>info</parameter> is <constant>NULL</constant>). The specified parameters match those of these
+    underlying system calls, except that the <parameter>info</parameter> is never modified (and is thus
+    declared constant). Like for the underlying system calls, the <parameter>flags</parameter> parameter
+    currently must be zero.</para>
   </refsect1>
 
   <refsect1>
@@ -196,6 +290,12 @@
           <listitem><para>The passed event source is not a child process event source.</para></listitem>
         </varlistentry>
 
+        <varlistentry>
+          <term><constant>-EOPNOTSUPP</constant></term>
+
+          <listitem><para>A pidfd was requested but the kernel does not support this concept.</para></listitem>
+        </varlistentry>
+
       </variablelist>
     </refsect2>
   </refsect1>
@@ -222,7 +322,11 @@
       <citerefentry><refentrytitle>sd_event_source_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
-      <citerefentry project='man-pages'><refentrytitle>pthread_sigmask</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      <citerefentry project='man-pages'><refentrytitle>pthread_sigmask</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>pidfd_open</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>pidfd_send_signal</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>rt_sigqueueinfo</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>
     </para>
   </refsect1>