Debian Codegraph @

upstream/debian-unstable/man3/sd_event_add_child.3

raw
1 '\" t
2 .TH "SD_EVENT_ADD_CHILD" "3" "" "systemd 261~rc3" "sd_event_add_child"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_event_add_child, sd_event_add_child_pidfd, sd_event_source_get_child_pid, sd_event_source_get_child_pidfd, sd_event_source_get_child_pidfd_own, sd_event_source_set_child_pidfd_own, sd_event_source_get_child_process_own, sd_event_source_set_child_process_own, sd_event_source_send_child_signal, sd_event_child_handler_t \- Add a child process state change event source to an event loop
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-event\&.h>
29 .fi
30 .ft
31 .sp
32 .ft B
33 .nf
34 typedef struct sd_event_source sd_event_source;
35 .fi
36 .ft
37 .HP \w'typedef\ int\ (*sd_event_child_handler_t)('u
38 .BI "typedef int (*sd_event_child_handler_t)(sd_event_source\ *" "s" ", const\ siginfo_t\ *" "si" ", void\ *" "userdata" ");"
39 .HP \w'int\ sd_event_add_child('u
40 .BI "int sd_event_add_child(sd_event\ *" "event" ", sd_event_source\ **" "source" ", pid_t\ " "pid" ", int\ " "options" ", sd_event_child_handler_t\ " "handler" ", void\ *" "userdata" ");"
41 .HP \w'int\ sd_event_add_child_pidfd('u
42 .BI "int sd_event_add_child_pidfd(sd_event\ *" "event" ", sd_event_source\ **" "source" ", int\ " "pidfd" ", int\ " "options" ", sd_event_child_handler_t\ " "handler" ", void\ *" "userdata" ");"
43 .HP \w'int\ sd_event_source_get_child_pid('u
44 .BI "int sd_event_source_get_child_pid(sd_event_source\ *" "source" ", pid_t\ *" "ret" ");"
45 .HP \w'int\ sd_event_source_get_child_pidfd('u
46 .BI "int sd_event_source_get_child_pidfd(sd_event_source\ *" "source" ");"
47 .HP \w'int\ sd_event_source_get_child_pidfd_own('u
48 .BI "int sd_event_source_get_child_pidfd_own(sd_event_source\ *" "source" ");"
49 .HP \w'int\ sd_event_source_set_child_pidfd_own('u
50 .BI "int sd_event_source_set_child_pidfd_own(sd_event_source\ *" "source" ", int\ " "own" ");"
51 .HP \w'int\ sd_event_source_get_child_process_own('u
52 .BI "int sd_event_source_get_child_process_own(sd_event_source\ *" "source" ");"
53 .HP \w'int\ sd_event_source_set_child_process_own('u
54 .BI "int sd_event_source_set_child_process_own(sd_event_source\ *" "source" ", int\ " "own" ");"
55 .HP \w'int\ sd_event_source_send_child_signal('u
56 .BI "int sd_event_source_send_child_signal(sd_event_source\ *" "source" ", int\ " "sig" ", const\ siginfo_t\ *" "info" ", unsigned\ " "flags" ");"
57 .SH "DESCRIPTION"
58 .PP
59 \fBsd_event_add_child()\fR
60 adds a new child process state change event source to an event loop\&. The event loop object is specified in the
61 \fIevent\fR
62 parameter, the event source object is returned in the
63 \fIsource\fR
64 parameter\&. The
65 \fIpid\fR
66 parameter specifies the PID of the process to watch, which must be a direct child process of the invoking process\&. The
67 \fIoptions\fR
68 parameter determines which state changes will be watched for\&. It must contain an OR\-ed mask of
69 \fBWEXITED\fR
70 (watch for the child process terminating),
71 \fBWSTOPPED\fR
72 (watch for the child process being stopped by a signal),
73 \fBWCONTINUED\fR
74 (watch for the child process being resumed by a signal) and
75 \fBWNOWAIT\fR
76 (Do not reap the child process after it exits)\&. See
77 \fBwaitid\fR(2)
78 for further information\&.
79 .PP
80 The
81 \fIhandler\fR
82 must be a function to call when the process changes state or
83 \fBNULL\fR\&. The handler function will be passed the
84 \fIuserdata\fR
85 pointer, which may be chosen freely by the caller\&. The handler also receives a pointer to a
86 siginfo_t
87 structure containing information about the child process event\&. The handler may return negative to signal an error (see below), other return values are ignored\&. If
88 \fIhandler\fR
89 is
90 \fBNULL\fR, a default handler that calls
91 \fBsd_event_exit\fR(3)
92 will be used\&.
93 .PP
94 Only a single handler may be installed for a specific child process\&. The handler is enabled for a single event (\fBSD_EVENT_ONESHOT\fR), but this may be changed with
95 \fBsd_event_source_set_enabled\fR(3)\&. If the handler function returns a negative error code, it will either be disabled after the invocation, even if the
96 \fBSD_EVENT_ON\fR
97 mode was requested before, or it will cause the loop to terminate, see
98 \fBsd_event_source_set_exit_on_failure\fR(3)\&.
99 .PP
100 To destroy an event source object use
101 \fBsd_event_source_unref\fR(3), 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\*(Aqs still a reference to it kept, consider setting the event source to
102 \fBSD_EVENT_OFF\fR
103 with
104 \fBsd_event_source_set_enabled\fR(3)\&.
105 .PP
106 The kernel autoreaping logic must be disabled for this function to work as expected (see
107 \fBsignal\fR(7))\&.
108 .PP
109 When watching for
110 \fBWSTOPPED\fR
111 or
112 \fBWCONTINUED\fR, the
113 \fBSIGCHLD\fR
114 signal must be blocked in all threads before this function is called (using
115 \fBsigprocmask\fR(2)
116 or
117 \fBpthread_sigmask\fR(3))\&.
118 .PP
119 If the second parameter of
120 \fBsd_event_add_child()\fR
121 is passed as
122 \fBNULL\fR
123 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\&.
124 .PP
125 Note that the
126 \fIhandler\fR
127 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\&.
128 .PP
129 If the
130 \fIhandler\fR
131 parameter to
132 \fBsd_event_add_child()\fR
133 is
134 \fBNULL\fR, and the event source fires, this will be considered a request to exit the event loop\&. In this case, the
135 \fIuserdata\fR
136 parameter, cast to an integer, is passed as the exit code parameter to
137 \fBsd_event_exit\fR(3)\&.
138 .PP
139 If both a child process state change event source and a
140 \fBSIGCHLD\fR
141 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\&.
142 .PP
143 \fBsd_event_add_child_pidfd()\fR
144 is similar to
145 \fBsd_event_add_child()\fR
146 but takes a file descriptor referencing the process ("pidfd") instead of the numeric PID\&. A suitable file descriptor may be acquired via
147 \fBpidfd_open\fR(2)
148 and related calls\&. The passed file descriptor is not closed when the event source is freed again, unless
149 \fBsd_event_source_set_child_pidfd_own()\fR
150 is used to turn this behaviour on\&. Note that regardless which of
151 \fBsd_event_add_child()\fR
152 and
153 \fBsd_event_add_child_pidfd()\fR
154 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
155 \fBSIGCHLD\fR
156 has to be blocked in the invoking process when watching for
157 \fBWSTOPPED\fR
158 or
159 \fBWCONTINUED\fR
160 and the kernel autoreaping logic has to be disabled\&.
161 .PP
162 \fBsd_event_source_get_child_pid()\fR
163 retrieves the configured PID of a child process state change event source created previously with
164 \fBsd_event_add_child()\fR\&. It takes the event source object as the
165 \fIsource\fR
166 parameter and a pointer to a
167 \fBpid_t\fR
168 variable to return the process ID in\&.
169 .PP
170 \fBsd_event_source_get_child_pidfd()\fR
171 retrieves the file descriptor referencing the watched process ("pidfd")\&. The event loop internally makes use of pidfds to watch child processes, regardless of whether the individual event sources are allocated via
172 \fBsd_event_add_child()\fR
173 or
174 \fBsd_event_add_child_pidfd()\fR\&. If the latter call was used to allocate the event source, this function returns the original file descriptor used for allocation\&. This call takes the event source object as the
175 \fIsource\fR
176 parameter and returns the numeric file descriptor\&.
177 .PP
178 \fBsd_event_source_get_child_pidfd_own()\fR
179 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
180 \fBsd_event_add_child()\fR
181 and off if it was allocated via
182 \fBsd_event_add_child_pidfd()\fR\&. The
183 \fBsd_event_source_set_child_pidfd_own()\fR
184 function may be used to change the setting and takes a boolean parameter with the new setting\&.
185 .PP
186 \fBsd_event_source_get_child_process_own()\fR
187 may be used to query whether the process the event source watches shall be killed (with
188 \fBSIGKILL\fR) 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
189 \fBsd_event_source_set_child_process_own()\fR
190 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\&.
191 .PP
192 \fBsd_event_source_send_child_signal()\fR
193 may be used to send a UNIX signal to the watched process via
194 \fBpidfd_send_signal\fR(2)\&. The specified parameters match those of the underlying system call, except that the
195 \fIinfo\fR
196 is never modified (and is thus declared constant)\&. Like for the underlying system call, the
197 \fIflags\fR
198 parameter currently must be zero\&.
199 .SH "RETURN VALUE"
200 .PP
201 On success, these functions return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
202 .SS "Errors"
203 .PP
204 Returned errors may indicate the following problems:
205 .PP
206 \fB\-ENOMEM\fR
207 .RS 4
208 Not enough memory to allocate an object\&.
209 .RE
210 .PP
211 \fB\-EINVAL\fR
212 .RS 4
213 An invalid argument has been passed\&. This includes specifying an empty mask in
214 \fIoptions\fR
215 or a mask which contains values different than a combination of
216 \fBWEXITED\fR,
217 \fBWSTOPPED\fR, and
218 \fBWCONTINUED\fR\&.
219 .RE
220 .PP
221 \fB\-EBUSY\fR
222 .RS 4
223 A handler is already installed for this child process, or
224 \fBSIGCHLD\fR
225 is not blocked\&.
226 .RE
227 .PP
228 \fB\-ESTALE\fR
229 .RS 4
230 The event loop is already terminated\&.
231 .RE
232 .PP
233 \fB\-ECHILD\fR
234 .RS 4
235 The event loop has been created in a different process, library or module instance\&.
236 .RE
237 .PP
238 \fB\-EDOM\fR
239 .RS 4
240 The passed event source is not a child process event source\&.
241 .RE
242 .SH "NOTES"
243 .PP
244 Functions described here are available as a shared library, which can be compiled against and linked to with the
245 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
246 file\&.
247 .PP
248 The code described here uses
249 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
250 \fBsetenv\fR(3)
251 from a parallel thread\&. It is recommended to only do calls to
252 \fBsetenv()\fR
253 from an early phase of the program when no other threads have been started\&.
254 .SH "EXAMPLE"
255 .PP
256 \fBExample\ \&1.\ \&Exit loop when the child terminates\fR
257 .sp
258 .if n \{\
259 .RS 4
260 .\}
261 .nf
262 /* SPDX\-License\-Identifier: MIT\-0 */
263
264 #define _GNU_SOURCE 1
265 #include <assert\&.h>
266 #include <stdio\&.h>
267 #include <unistd\&.h>
268 #include <systemd/sd\-event\&.h>
269
270 int main(int argc, char **argv) {
271 pid_t pid = fork();
272 assert(pid >= 0);
273
274 if (pid == 0) /* child */
275 sleep(1);
276
277 else { /* parent */
278 sd_event *e = NULL;
279 int r;
280
281 /* Create the default event loop */
282 sd_event_default(&e);
283 assert(e);
284
285 /* We create a floating child event source (attached to \*(Aqe\*(Aq)\&.
286 * The default handler will be called with 666 as userdata, which
287 * will become the exit value of the loop\&. */
288 r = sd_event_add_child(e, NULL, pid, WEXITED, NULL, (void*) 666);
289 assert(r >= 0);
290
291 r = sd_event_loop(e);
292 assert(r == 666);
293
294 sd_event_unref(e);
295 }
296
297 return 0;
298 }
299 .fi
300 .if n \{\
301 .RE
302 .\}
303 .SH "HISTORY"
304 .PP
305 \fBsd_event_add_child()\fR,
306 \fBsd_event_child_handler_t()\fR, and
307 \fBsd_event_source_get_child_pid()\fR
308 were added in version 217\&.
309 .PP
310 \fBsd_event_add_child_pidfd()\fR,
311 \fBsd_event_source_get_child_pidfd()\fR,
312 \fBsd_event_source_get_child_pidfd_own()\fR,
313 \fBsd_event_source_set_child_pidfd_own()\fR,
314 \fBsd_event_source_get_child_process_own()\fR,
315 \fBsd_event_source_set_child_process_own()\fR, and
316 \fBsd_event_source_send_child_signal()\fR
317 were added in version 245\&.
318 .SH "SEE ALSO"
319 .PP
320 \fBsystemd\fR(1), \fBsd-event\fR(3), \fBsd_event_new\fR(3), \fBsd_event_now\fR(3), \fBsd_event_add_io\fR(3), \fBsd_event_add_time\fR(3), \fBsd_event_add_signal\fR(3), \fBsd_event_add_inotify\fR(3), \fBsd_event_add_defer\fR(3), \fBsd_event_source_set_enabled\fR(3), \fBsd_event_source_set_priority\fR(3), \fBsd_event_source_set_userdata\fR(3), \fBsd_event_source_set_description\fR(3), \fBsd_event_source_set_floating\fR(3), \fBwaitid\fR(2), \fBsigprocmask\fR(2), \fBpthread_sigmask\fR(3), \fBpidfd_open\fR(2), \fBpidfd_send_signal\fR(2), \fBrt_sigqueueinfo\fR(2), \fBkill\fR(2)