man: document the new sd-event pidfd magic
This commit is contained in:
parent
b350807200
commit
8089643328
|
@ -371,7 +371,15 @@ manpages = [
|
||||||
['sd_bus_wait', '3', [], ''],
|
['sd_bus_wait', '3', [], ''],
|
||||||
['sd_event_add_child',
|
['sd_event_add_child',
|
||||||
'3',
|
'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',
|
['sd_event_add_defer',
|
||||||
'3',
|
'3',
|
||||||
|
|
|
@ -17,7 +17,14 @@
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>sd_event_add_child</refname>
|
<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_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>
|
<refname>sd_event_child_handler_t</refname>
|
||||||
|
|
||||||
<refpurpose>Add a child process state change event source to an event loop</refpurpose>
|
<refpurpose>Add a child process state change event source to an event loop</refpurpose>
|
||||||
|
@ -46,40 +53,77 @@
|
||||||
<paramdef>void *<parameter>userdata</parameter></paramdef>
|
<paramdef>void *<parameter>userdata</parameter></paramdef>
|
||||||
</funcprototype>
|
</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>
|
<funcprototype>
|
||||||
<funcdef>int <function>sd_event_source_get_child_pid</function></funcdef>
|
<funcdef>int <function>sd_event_source_get_child_pid</function></funcdef>
|
||||||
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
|
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
|
||||||
<paramdef>pid_t *<parameter>pid</parameter></paramdef>
|
<paramdef>pid_t *<parameter>pid</parameter></paramdef>
|
||||||
</funcprototype>
|
</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>
|
</funcsynopsis>
|
||||||
</refsynopsisdiv>
|
</refsynopsisdiv>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<title>Description</title>
|
<title>Description</title>
|
||||||
|
|
||||||
<para><function>sd_event_add_child()</function> adds a new child
|
<para><function>sd_event_add_child()</function> adds a new child process state change event source to an
|
||||||
process state change event source to an event loop. The event loop
|
event loop. The event loop object is specified in the <parameter>event</parameter> parameter, the event
|
||||||
object is specified in the <parameter>event</parameter> parameter,
|
source object is returned in the <parameter>source</parameter> parameter. The <parameter>pid</parameter>
|
||||||
the event source object is returned in the
|
parameter specifies the PID of the process to watch, which must be a direct child process of the invoking
|
||||||
<parameter>source</parameter> parameter. The
|
process. The <parameter>handler</parameter> must reference a function to call when the process changes
|
||||||
<parameter>pid</parameter> parameter specifies the PID of the
|
state. The handler function will be passed the <parameter>userdata</parameter> pointer, which may be
|
||||||
process to watch. The <parameter>handler</parameter> must
|
chosen freely by the caller. The handler also receives a pointer to a <structname>siginfo_t</structname>
|
||||||
reference a function to call when the process changes state. The
|
structure containing information about the child process event. The <parameter>options</parameter>
|
||||||
handler function will be passed the
|
parameter determines which state changes will be watched for. It must contain an OR-ed mask of
|
||||||
<parameter>userdata</parameter> pointer, which may be chosen
|
<constant>WEXITED</constant> (watch for the child process terminating), <constant>WSTOPPED</constant>
|
||||||
freely by the caller. The handler also receives a pointer to a
|
(watch for the child process being stopped by a signal), and <constant>WCONTINUED</constant> (watch for
|
||||||
<structname>siginfo_t</structname> structure containing
|
the child process being resumed by a signal). See <citerefentry
|
||||||
information about the child process event. The
|
project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
|
||||||
<parameter>options</parameter> parameter determines which state
|
further information.</para>
|
||||||
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
|
<para>Only a single handler may be installed for a specific
|
||||||
child process. The handler is enabled for a single event
|
child process. The handler is enabled for a single event
|
||||||
|
@ -127,6 +171,17 @@
|
||||||
processed first, it should leave the child processes for which
|
processed first, it should leave the child processes for which
|
||||||
child process state change event sources are installed unreaped.</para>
|
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>
|
<para><function>sd_event_source_get_child_pid()</function>
|
||||||
retrieves the configured PID of a child process state change event
|
retrieves the configured PID of a child process state change event
|
||||||
source created previously with
|
source created previously with
|
||||||
|
@ -135,6 +190,45 @@
|
||||||
pointer to a <type>pid_t</type> variable to return the process ID
|
pointer to a <type>pid_t</type> variable to return the process ID
|
||||||
in.
|
in.
|
||||||
</para>
|
</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>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
|
@ -196,6 +290,12 @@
|
||||||
<listitem><para>The passed event source is not a child process event source.</para></listitem>
|
<listitem><para>The passed event source is not a child process event source.</para></listitem>
|
||||||
</varlistentry>
|
</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>
|
</variablelist>
|
||||||
</refsect2>
|
</refsect2>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
@ -222,7 +322,11 @@
|
||||||
<citerefentry><refentrytitle>sd_event_source_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<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>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
|
||||||
<citerefentry project='man-pages'><refentrytitle>sigprocmask</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>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue