1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 Copyright © 2014 Zbigniew Jędrzejewski-Szmek
11 <refentry id="sd_event_add_child" xmlns:xi="http://www.w3.org/2001/XInclude">
14 <title>sd_event_add_child</title>
15 <productname>systemd</productname>
19 <refentrytitle>sd_event_add_child</refentrytitle>
20 <manvolnum>3</manvolnum>
24 <refname>sd_event_add_child</refname>
25 <refname>sd_event_source_get_child_pid</refname>
26 <refname>sd_event_child_handler_t</refname>
28 <refpurpose>Add a child process state change event source to an event loop</refpurpose>
33 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
35 <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
38 <funcdef>typedef int (*<function>sd_event_child_handler_t</function>)</funcdef>
39 <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
40 <paramdef>const siginfo_t *<parameter>si</parameter></paramdef>
41 <paramdef>void *<parameter>userdata</parameter></paramdef>
45 <funcdef>int <function>sd_event_add_child</function></funcdef>
46 <paramdef>sd_event *<parameter>event</parameter></paramdef>
47 <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
48 <paramdef>pid_t <parameter>pid</parameter></paramdef>
49 <paramdef>int <parameter>options</parameter></paramdef>
50 <paramdef>sd_event_child_handler_t <parameter>handler</parameter></paramdef>
51 <paramdef>void *<parameter>userdata</parameter></paramdef>
55 <funcdef>int <function>sd_event_source_get_child_pid</function></funcdef>
56 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
57 <paramdef>pid_t *<parameter>pid</parameter></paramdef>
64 <title>Description</title>
66 <para><function>sd_event_add_child()</function> adds a new child
67 process state change event source to an event loop. The event loop
68 object is specified in the <parameter>event</parameter> parameter,
69 the event source object is returned in the
70 <parameter>source</parameter> parameter. The
71 <parameter>pid</parameter> parameter specifies the PID of the
72 process to watch. The <parameter>handler</parameter> must
73 reference a function to call when the process changes state. The
74 handler function will be passed the
75 <parameter>userdata</parameter> pointer, which may be chosen
76 freely by the caller. The handler also receives a pointer to a
77 <structname>siginfo_t</structname> structure containing
78 information about the child process event. The
79 <parameter>options</parameter> parameter determines which state
80 changes will be watched for. It must contain an OR-ed mask of
81 <constant>WEXITED</constant> (watch for the child process
82 terminating), <constant>WSTOPPED</constant> (watch for the child
83 process being stopped by a signal), and
84 <constant>WCONTINUED</constant> (watch for the child process being
85 resumed by a signal). See <citerefentry
86 project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
87 for further information.</para>
89 <para>Only a single handler may be installed for a specific
90 child process. The handler is enabled for a single event
91 (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
93 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
94 If the handler function returns a negative error code, it will be
95 disabled after the invocation, even if the
96 <constant>SD_EVENT_ON</constant> mode was requested before.
99 <para>To destroy an event source object use
100 <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
101 but note that the event source is only removed from the event loop
102 when all references to the event source are dropped. To make sure
103 an event source does not fire anymore, even when there's still a
104 reference to it kept, consider setting the event source to
105 <constant>SD_EVENT_OFF</constant> with
106 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
108 <para>If the second parameter of
109 <function>sd_event_add_child()</function> is passed as NULL no
110 reference to the event source object is returned. In this case the
111 event source is considered "floating", and will be destroyed
112 implicitly when the event loop itself is destroyed.</para>
114 <para>Note that the <parameter>handler</parameter> function is
115 invoked at a time where the child process is not reaped yet (and
116 thus still is exposed as a zombie process by the kernel). However,
117 the child will be reaped automatically after the function
118 returns. Child processes for which no child process state change
119 event sources are installed will not be reaped by the event loop
120 implementation.</para>
122 <para>If both a child process state change event source and a
123 <constant>SIGCHLD</constant> signal event source is installed in
124 the same event loop, the configured event source priorities decide
125 which event source is dispatched first. If the signal handler is
126 processed first, it should leave the child processes for which
127 child process state change event sources are installed unreaped.</para>
129 <para><function>sd_event_source_get_child_pid()</function>
130 retrieves the configured PID of a child process state change event
131 source created previously with
132 <function>sd_event_add_child()</function>. It takes the event
133 source object as the <parameter>source</parameter> parameter and a
134 pointer to a <type>pid_t</type> variable to return the process ID
140 <title>Return Value</title>
142 <para>On success, these functions return 0 or a positive
143 integer. On failure, they return a negative errno-style error
148 <title>Errors</title>
150 <para>Returned errors may indicate the following problems:</para>
154 <term><constant>-ENOMEM</constant></term>
156 <listitem><para>Not enough memory to allocate an object.</para></listitem>
160 <term><constant>-EINVAL</constant></term>
162 <listitem><para>An invalid argument has been passed. This includes
163 specifying an empty mask in <parameter>options</parameter> or a mask
164 which contains values different than a combination of
165 <constant>WEXITED</constant>, <constant>WSTOPPED</constant>, and
166 <constant>WCONTINUED</constant>.
172 <term><constant>-EBUSY</constant></term>
174 <listitem><para>A handler is already installed for this
175 child process.</para></listitem>
180 <term><constant>-ESTALE</constant></term>
182 <listitem><para>The event loop is already terminated.</para></listitem>
187 <term><constant>-ECHILD</constant></term>
189 <listitem><para>The event loop has been created in a different process.</para></listitem>
194 <term><constant>-EDOM</constant></term>
196 <listitem><para>The passed event source is not a child process event source.</para></listitem>
202 <xi:include href="libelogind-pkgconfig.xml" />
205 <title>See Also</title>
208 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
209 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
210 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
211 <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
212 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
213 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
214 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
215 <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
216 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
217 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
218 <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
219 <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
220 <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
221 <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>