man: document the new sd-event pidfd magic
This commit is contained in:
Lennart Poettering
parent
b350807200
commit
8089643328
|
|
@ -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',
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue