summaryrefslogtreecommitdiff
path: root/man/sd_event_add_child.xml
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2015-11-19 23:38:54 +0100
committerLennart Poettering <lennart@poettering.net>2015-11-19 23:38:54 +0100
commitdc83f27a7cf03757dec11a69ec18504ad4ea8f89 (patch)
tree54af47fe95cdaa44ea4f0e3c0c3482e40c46edc3 /man/sd_event_add_child.xml
parent0be6c2f617732902921d42bb0705f016b2838aba (diff)
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.
Diffstat (limited to 'man/sd_event_add_child.xml')
-rw-r--r--man/sd_event_add_child.xml132
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>