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 handler must
58 reference a function to call when the process changes state. The
59 handler function will be passed the userdata pointer, which may be
60 chosen freely by the caller. The handler also receives a pointer to a
61 siginfo_t structure containing information about the child process
62 event. The options parameter determines which state changes will be
63 watched for. It must contain an OR-ed mask of WEXITED (watch for the
64 child process terminating), WSTOPPED (watch for the child process being
65 stopped by a signal), and WCONTINUED (watch for the child process being
66 resumed by a signal). See waitid(2) for further information.
67 Only a single handler may be installed for a specific child process.
69 The handler is enabled for a single event (SD_EVENT_ONESHOT), but this
70 may be changed with sd_event_source_set_enabled(3). If the handler
71 function returns a negative error code, it will be disabled after the
72 invocation, even if the SD_EVENT_ON mode was requested before.
73 To destroy an event source object use sd_event_source_unref(3), but
75 note that the event source is only removed from the event loop when all
76 references to the event source are dropped. To make sure an event
77 source does not fire anymore, even when there's still a reference to it
78 kept, consider setting the event source to SD_EVENT_OFF with
79 sd_event_source_set_enabled(3).
80 The SIGCHLD signal must be blocked in all threads before this function
82 is called (using sigprocmask(2) or pthread_sigmask(3)).
83 If the second parameter of sd_event_add_child() is passed as NULL no
85 reference to the event source object is returned. In this case the
86 event source is considered "floating", and will be destroyed implicitly
87 when the event loop itself is destroyed.
88 Note that the handler function is invoked at a time where the child
90 process is not reaped yet (and thus still is exposed as a zombie
91 process by the kernel). However, the child will be reaped automatically
92 after the function returns. Child processes for which no child process
93 state change event sources are installed will not be reaped by the
94 event loop implementation.
95 If the handler parameter to sd_event_add_child() is NULL, and the event
97 source fires, this will be considered a request to exit the event loop.
98 In this case, the userdata parameter, cast to an integer, is passed as
99 the exit code parameter to sd_event_exit(3).
100 If both a child process state change event source and a SIGCHLD signal
102 event source is installed in the same event loop, the configured event
103 source priorities decide which event source is dispatched first. If the
104 signal handler is processed first, it should leave the child processes
105 for which child process state change event sources are installed
106 unreaped.
107 sd_event_add_child_pidfd() is similar to sd_event_add_child() but takes
109 a file descriptor referencing the process ("pidfd") instead of the
110 numeric PID. A suitable file descriptor may be acquired via
111 pidfd_open(2) and related calls. The passed file descriptor is not
112 closed when the event source is freed again, unless
113 sd_event_source_set_child_pidfd_own() is used to turn this behaviour
114 on. Note that regardless which of sd_event_add_child() and
115 sd_event_add_child_pidfd() is used for allocating an event source, the
116 watched process has to be a direct child process of the invoking
117 process. Also in both cases SIGCHLD has to be blocked in the invoking
118 process.
119 sd_event_source_get_child_pid() retrieves the configured PID of a child
121 process state change event source created previously with
122 sd_event_add_child(). It takes the event source object as the source
123 parameter and a pointer to a pid_t variable to return the process ID
124 in.
125 sd_event_source_get_child_pidfd() retrieves the file descriptor
127 referencing the watched process ("pidfd") if this functionality is
128 available. On kernels that support the concept the event loop will make
129 use of pidfds to watch child processes, regardless if the individual
130 event sources are allocated via sd_event_add_child() or
131 sd_event_add_child_pidfd(). If the latter call was used to allocate the
132 event source, this function returns the file descriptor used for
133 allocation. On kernels that do not support the pidfd concept this
134 function will fail with EOPNOTSUPP. This call takes the event source
135 object as the source parameter and returns the numeric file descriptor.
136 sd_event_source_get_child_pidfd_own() may be used to query whether the
138 pidfd the event source encapsulates shall be closed when the event
139 source is freed. This function returns zero if the pidfd shall be left
140 open, and positive if it shall be closed automatically. By default this
141 setting defaults to on if the event source was allocated via
142 sd_event_add_child() and off if it was allocated via
143 sd_event_add_child_pidfd(). The sd_event_source_set_child_pidfd_own()
144 function may be used to change the setting and takes a boolean
145 parameter with the new setting.
146 sd_event_source_get_child_process_own() may be used to query whether
148 the process the event source watches shall be killed (with SIGKILL) and
149 reaped when the event source is freed. This function returns zero if
150 the process shell be left running, and positive if it shall be killed
151 and reaped automatically. By default this setting defaults to off. The
152 sd_event_source_set_child_process_own() function may be used to change
153 the setting and takes a boolean parameter with the new setting. Note
154 that currently if the calling process is terminated abnormally the
155 watched process might survive even thought the event source ceases to
156 exist. This behaviour might change eventually.
157 sd_event_source_send_child_signal() may be used to send a UNIX signal
159 to the watched process. If the pidfd concept is supported in the
160 kernel, this is implemented via pidfd_send_signal(2) and otherwise via
161 rt_sigqueueinfo(2) (or via kill(2) in case info is NULL). The specified
162 parameters match those of these underlying system calls, except that
163 the info is never modified (and is thus declared constant). Like for
164 the underlying system calls, the flags parameter currently must be
165 zero.
166
168 On success, these functions return 0 or a positive integer. On failure,
169 they return a negative errno-style error code.
170 Errors
172 Returned errors may indicate the following problems:
173 -ENOMEM
175 Not enough memory to allocate an object.
176 -EINVAL
178 An invalid argument has been passed. This includes specifying an
179 empty mask in options or a mask which contains values different
180 than a combination of WEXITED, WSTOPPED, and WCONTINUED.
181 -EBUSY
183 A handler is already installed for this child process, or SIGCHLD
184 is not blocked.
185 -ESTALE
187 The event loop is already terminated.
188 -ECHILD
190 The event loop has been created in a different process.
191 -EDOM
193 The passed event source is not a child process event source.
194 -EOPNOTSUPP
196 A pidfd was requested but the kernel does not support this concept.
197
199 These APIs are implemented as a shared library, which can be compiled
200 and linked to with the libsystemd pkg-config(1) file.
201
203 systemd(1), sd-event(3), sd_event_new(3), sd_event_now(3),
204 sd_event_add_io(3), sd_event_add_time(3), sd_event_add_signal(3),
205 sd_event_add_inotify(3), sd_event_add_defer(3),
206 sd_event_source_set_enabled(3), sd_event_source_set_priority(3),
207 sd_event_source_set_userdata(3), sd_event_source_set_description(3),
208 sd_event_source_set_floating(3), waitid(2), sigprocmask(2),
209 pthread_sigmask(3), pidfd_open(2), pidfd_send_signal(2),
210 rt_sigqueueinfo(2), kill(2)
211systemd 250 SD_EVENT_ADD_CHILD(3)