"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
-This file is part of systemd.
+ This file is part of systemd.
-Copyright 2014 Zbigniew Jędrzejewski-Szmek
+ Copyright 2014 Zbigniew Jędrzejewski-Szmek
-systemd is free software; you can redistribute it and/or modify it
-under the terms of the GNU Lesser General Public License as published by
-the Free Software Foundation; either version 2.1 of the License, or
-(at your option) any later version.
+ systemd is free software; you can redistribute it and/or modify it
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or
+ (at your option) any later version.
-systemd is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-Lesser General Public License for more details.
+ systemd is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
-You should have received a copy of the GNU Lesser General Public License
-along with systemd; If not, see <http://www.gnu.org/licenses/>.
+ You should have received a copy of the GNU Lesser General Public License
+ along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="sd_event_add_child" conditional="ENABLE_KDBUS">
+<refentry id="sd_event_add_child" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_add_child</title>
<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 <systemd/sd-bus.h></funcsynopsisinfo>
+ <funcsynopsisinfo>#include <systemd/sd-event.h></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>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</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>
<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 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>
<term><constant>-EINVAL</constant></term>
<listitem><para>An invalid argument has been passed. This includes
- spec
yfing an empty mask in <parameter>options</parameter> or a mask
+ spec
ifying an empty mask in <parameter>options</parameter> or a mask
which contains values different than a combination of
<constant>WEXITED</constant>, <constant>WSTOPPED</constant>, and
<constant>WCONTINUED</constant>.
<varlistentry>
<term><constant>-EBUSY</constant></term>
- <listitem><para>An handler is already installed for this
- child.</para></listitem>
+ <listitem><para>A handler is already installed for this
+ child process.</para></listitem>
</varlistentry>
</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="libelogind-pkgconfig.xml" />
+
<refsect1>
<title>See Also</title>
<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>
~ianmdlvl / elogind.git / blobdiff