1SD_EVENT_ADD_CHILD(3) sd_event_add_child SD_EVENT_ADD_CHILD(3)
2
6 sd_event_add_child, sd_event_add_child_pidfd,
7 sd_event_source_get_child_pid, sd_event_source_get_child_pidfd,
8 sd_event_source_get_child_pidfd_own,
9 sd_event_source_set_child_pidfd_own,
10 sd_event_source_get_child_process_own,
11 sd_event_source_set_child_process_own,
12 sd_event_source_send_child_signal, sd_event_child_handler_t - Add a
13 child process state change event source to an event loop
14
16 #include <systemd/sd-event.h>
17 typedef struct sd_event_source sd_event_source;
19 typedef int (*sd_event_child_handler_t)(sd_event_source *s,
21 const siginfo_t *si,
22 void *userdata);
23 int sd_event_add_child(sd_event *event, sd_event_source **source,
25 pid_t pid, int options,
26 sd_event_child_handler_t handler,
27 void *userdata);
28 int sd_event_add_child_pidfd(sd_event *event, sd_event_source **source,
30 int pidfd, int options,
31 sd_event_child_handler_t handler,
32 void *userdata);
33 int sd_event_source_get_child_pid(sd_event_source *source, pid_t *pid);
35 int sd_event_source_get_child_pidfd(sd_event_source *source);
37 int sd_event_source_get_child_pidfd_own(sd_event_source *source);
39 int sd_event_source_set_child_pidfd_own(sd_event_source *source,
41 int own);
42 int sd_event_source_get_child_process_own(sd_event_source *source);
44 int sd_event_source_set_child_process_own(sd_event_source *source,
46 int own);
47 int sd_event_source_send_child_signal(sd_event_source *source, int sig,
49 const siginfo_t *info,
50 unsigned flags);
51
53 sd_event_add_child() adds a new child process state change event source
54 to an event loop. The event loop object is specified in the event
55 parameter, the event source object is returned in the source parameter.
56 The pid parameter specifies the PID of the process to watch, which must
57 be a direct child process of the invoking process. The options
58 parameter determines which state changes will be watched for. It must
59 contain an OR-ed mask of WEXITED (watch for the child process
60 terminating), WSTOPPED (watch for the child process being stopped by a
61 signal), and WCONTINUED (watch for the child process being resumed by a
62 signal). See waitid(2) for further information.
63 The handler must be a function to call when the process changes state
65 or NULL. The handler function will be passed the userdata pointer,
66 which may be chosen freely by the caller. The handler also receives a
67 pointer to a siginfo_t structure containing information about the child
68 process event. The handler may return negative to signal an error (see
69 below), other return values are ignored. If handler is NULL, a default
70 handler that calls sd_event_exit(3) will be used.
71 Only a single handler may be installed for a specific child process.
73 The handler is enabled for a single event (SD_EVENT_ONESHOT), but this
74 may be changed with sd_event_source_set_enabled(3). If the handler
75 function returns a negative error code, it will either be disabled
76 after the invocation, even if the SD_EVENT_ON mode was requested
77 before, or it will cause the loop to terminate, see
78 sd_event_source_set_exit_on_failure(3).
79 To destroy an event source object use sd_event_source_unref(3), but
81 note that the event source is only removed from the event loop when all
82 references to the event source are dropped. To make sure an event
83 source does not fire anymore, even when there's still a reference to it
84 kept, consider setting the event source to SD_EVENT_OFF with
85 sd_event_source_set_enabled(3).
86 The SIGCHLD signal must be blocked in all threads before this function
88 is called (using sigprocmask(2) or pthread_sigmask(3)).
89 If the second parameter of sd_event_add_child() is passed as NULL no
91 reference to the event source object is returned. In this case the
92 event source is considered "floating", and will be destroyed implicitly
93 when the event loop itself is destroyed.
94 Note that the handler function is invoked at a time where the child
96 process is not reaped yet (and thus still is exposed as a zombie
97 process by the kernel). However, the child will be reaped automatically
98 after the function returns. Child processes for which no child process
99 state change event sources are installed will not be reaped by the
100 event loop implementation.
101 If the handler parameter to sd_event_add_child() is NULL, and the event
103 source fires, this will be considered a request to exit the event loop.
104 In this case, the userdata parameter, cast to an integer, is passed as
105 the exit code parameter to sd_event_exit(3).
106 If both a child process state change event source and a SIGCHLD signal
108 event source is installed in the same event loop, the configured event
109 source priorities decide which event source is dispatched first. If the
110 signal handler is processed first, it should leave the child processes
111 for which child process state change event sources are installed
112 unreaped.
113 sd_event_add_child_pidfd() is similar to sd_event_add_child() but takes
115 a file descriptor referencing the process ("pidfd") instead of the
116 numeric PID. A suitable file descriptor may be acquired via
117 pidfd_open(2) and related calls. The passed file descriptor is not
118 closed when the event source is freed again, unless
119 sd_event_source_set_child_pidfd_own() is used to turn this behaviour
120 on. Note that regardless which of sd_event_add_child() and
121 sd_event_add_child_pidfd() is used for allocating an event source, the
122 watched process has to be a direct child process of the invoking
123 process. Also in both cases SIGCHLD has to be blocked in the invoking
124 process.
125 sd_event_source_get_child_pid() retrieves the configured PID of a child
127 process state change event source created previously with
128 sd_event_add_child(). It takes the event source object as the source
129 parameter and a pointer to a pid_t variable to return the process ID
130 in.
131 sd_event_source_get_child_pidfd() retrieves the file descriptor
133 referencing the watched process ("pidfd") if this functionality is
134 available. On kernels that support the concept the event loop will make
135 use of pidfds to watch child processes, regardless if the individual
136 event sources are allocated via sd_event_add_child() or
137 sd_event_add_child_pidfd(). If the latter call was used to allocate the
138 event source, this function returns the file descriptor used for
139 allocation. On kernels that do not support the pidfd concept this
140 function will fail with EOPNOTSUPP. This call takes the event source
141 object as the source parameter and returns the numeric file descriptor.
142 sd_event_source_get_child_pidfd_own() may be used to query whether the
144 pidfd the event source encapsulates shall be closed when the event
145 source is freed. This function returns zero if the pidfd shall be left
146 open, and positive if it shall be closed automatically. By default this
147 setting defaults to on if the event source was allocated via
148 sd_event_add_child() and off if it was allocated via
149 sd_event_add_child_pidfd(). The sd_event_source_set_child_pidfd_own()
150 function may be used to change the setting and takes a boolean
151 parameter with the new setting.
152 sd_event_source_get_child_process_own() may be used to query whether
154 the process the event source watches shall be killed (with SIGKILL) and
155 reaped when the event source is freed. This function returns zero if
156 the process shell be left running, and positive if it shall be killed
157 and reaped automatically. By default this setting defaults to off. The
158 sd_event_source_set_child_process_own() function may be used to change
159 the setting and takes a boolean parameter with the new setting. Note
160 that currently if the calling process is terminated abnormally the
161 watched process might survive even thought the event source ceases to
162 exist. This behaviour might change eventually.
163 sd_event_source_send_child_signal() may be used to send a UNIX signal
165 to the watched process. If the pidfd concept is supported in the
166 kernel, this is implemented via pidfd_send_signal(2) and otherwise via
167 rt_sigqueueinfo(2) (or via kill(2) in case info is NULL). The specified
168 parameters match those of these underlying system calls, except that
169 the info is never modified (and is thus declared constant). Like for
170 the underlying system calls, the flags parameter currently must be
171 zero.
172
174 On success, these functions return 0 or a positive integer. On failure,
175 they return a negative errno-style error code.
176 Errors
178 Returned errors may indicate the following problems:
179 -ENOMEM
181 Not enough memory to allocate an object.
182 -EINVAL
184 An invalid argument has been passed. This includes specifying an
185 empty mask in options or a mask which contains values different
186 than a combination of WEXITED, WSTOPPED, and WCONTINUED.
187 -EBUSY
189 A handler is already installed for this child process, or SIGCHLD
190 is not blocked.
191 -ESTALE
193 The event loop is already terminated.
194 -ECHILD
196 The event loop has been created in a different process.
197 -EDOM
199 The passed event source is not a child process event source.
200 -EOPNOTSUPP
202 A pidfd was requested but the kernel does not support this concept.
203
205 These APIs are implemented as a shared library, which can be compiled
206 and linked to with the libsystemd pkg-config(1) file.
207
209 Example 1. Exit loop when the child terminates
210 /* SPDX-License-Identifier: MIT-0 */
212 #include <assert.h>
214 #include <stdio.h>
215 #include <unistd.h>
216 #include <sd-event.h>
217 int main(int argc, char **argv) {
219 pid_t pid = fork();
220 assert(pid >= 0);
221 /* SIGCHLD signal must be blocked for sd_event_add_child to work */
223 sigset_t ss;
224 sigemptyset(&ss);
225 sigaddset(&ss, SIGCHLD);
226 sigprocmask(SIG_BLOCK, &ss, NULL);
227 if (pid == 0) /* child */
229 sleep(1);
230 else { /* parent */
232 sd_event *e = NULL;
233 int r;
234 /* Create the default event loop */
236 sd_event_default(&e);
237 assert(e);
238 /* We create a floating child event source (attached to 'e').
240 * The default handler will be called with 666 as userdata, which
241 * will become the exit value of the loop. */
242 r = sd_event_add_child(e, NULL, pid, WEXITED, NULL, (void*) 666);
243 assert(r >= 0);
244 r = sd_event_loop(e);
246 assert(r == 666);
247 sd_event_unref(e);
249 }
250 return 0;
252 }
253
255 systemd(1), sd-event(3), sd_event_new(3), sd_event_now(3),
256 sd_event_add_io(3), sd_event_add_time(3), sd_event_add_signal(3),
257 sd_event_add_inotify(3), sd_event_add_defer(3),
258 sd_event_source_set_enabled(3), sd_event_source_set_priority(3),
259 sd_event_source_set_userdata(3), sd_event_source_set_description(3),
260 sd_event_source_set_floating(3), waitid(2), sigprocmask(2),
261 pthread_sigmask(3), pidfd_open(2), pidfd_send_signal(2),
262 rt_sigqueueinfo(2), kill(2)
263systemd 253 SD_EVENT_ADD_CHILD(3)