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 both a child process state change event source and a SIGCHLD signal
97 event source is installed in the same event loop, the configured event
98 source priorities decide which event source is dispatched first. If the
99 signal handler is processed first, it should leave the child processes
100 for which child process state change event sources are installed
101 unreaped.
102 sd_event_add_child_pidfd() is similar to sd_event_add_child() but takes
104 a file descriptor referencing the process ("pidfd") instead of the
105 numeric PID. A suitable file descriptor may be acquired via
106 pidfd_open(2) and related calls. The passed file descriptor is not
107 closed when the event source is freed again, unless
108 sd_event_source_set_child_pidfd_own() is used to turn this behaviour
109 on. Note that regardless which of sd_event_add_child() and
110 sd_event_add_child_pidfd() is used for allocating an event source, the
111 watched process has to be a direct child process of the invoking
112 process. Also in both cases SIGCHLD has to be blocked in the invoking
113 process.
114 sd_event_source_get_child_pid() retrieves the configured PID of a child
116 process state change event source created previously with
117 sd_event_add_child(). It takes the event source object as the source
118 parameter and a pointer to a pid_t variable to return the process ID
119 in.
120 sd_event_source_get_child_pidfd() retrieves the file descriptor
122 referencing the watched process ("pidfd") if this functionality is
123 available. On kernels that support the concept the event loop will make
124 use of pidfds to watch child processes, regardless if the individual
125 event sources are allocated via sd_event_add_child() or
126 sd_event_add_child_pidfd(). If the latter call was used to allocate the
127 event source, this function returns the file descriptor used for
128 allocation. On kernels that do not support the pidfd concept this
129 function will fail with EOPNOTSUPP. This call takes the event source
130 object as the source parameter and returns the numeric file descriptor.
131 sd_event_source_get_child_pidfd_own() may be used to query whether the
133 pidfd the event source encapsulates shall be closed when the event
134 source is freed. This function returns zero if the pidfd shall be left
135 open, and positive if it shall be closed automatically. By default this
136 setting defaults to on if the event source was allocated via
137 sd_event_add_child() and off if it was allocated via
138 sd_event_add_child_pidfd(). The sd_event_source_set_child_pidfd_own()
139 function may be used to change the setting and takes a boolean
140 parameter with the new setting.
141 sd_event_source_get_child_process_own() may be used to query whether
143 the process the event source watches shall be killed (with SIGKILL) and
144 reaped when the event source is freed. This function returns zero if
145 the process shell be left running, and positive if it shall be killed
146 and reaped automatically. By default this setting defaults to off. The
147 sd_event_source_set_child_process_own() function may be used to change
148 the setting and takes a boolean parameter with the new setting. Note
149 that currently if the calling process is terminated abnormally the
150 watched process might survive even thought the event source ceases to
151 exist. This behaviour might change eventually.
152 sd_event_source_send_child_signal() may be used to send a UNIX signal
154 to the watched process. If the pidfd concept is supported in the
155 kernel, this is implemented via pidfd_send_signal(2) and otherwise via
156 rt_sigqueueinfo(2) (or via kill(2) in case info is NULL). The specified
157 parameters match those of these underlying system calls, except that
158 the info is never modified (and is thus declared constant). Like for
159 the underlying system calls, the flags parameter currently must be
160 zero.
161
163 On success, these functions return 0 or a positive integer. On failure,
164 they return a negative errno-style error code.
165 Errors
167 Returned errors may indicate the following problems:
168 -ENOMEM
170 Not enough memory to allocate an object.
171 -EINVAL
173 An invalid argument has been passed. This includes specifying an
174 empty mask in options or a mask which contains values different
175 than a combination of WEXITED, WSTOPPED, and WCONTINUED.
176 -EBUSY
178 A handler is already installed for this child process, or SIGCHLD
179 is not blocked.
180 -ESTALE
182 The event loop is already terminated.
183 -ECHILD
185 The event loop has been created in a different process.
186 -EDOM
188 The passed event source is not a child process event source.
189 -EOPNOTSUPP
191 A pidfd was requested but the kernel does not support this concept.
192
194 These APIs are implemented as a shared library, which can be compiled
195 and linked to with the libsystemd pkg-config(1) file.
196
198 systemd(1), sd-event(3), sd_event_new(3), sd_event_now(3),
199 sd_event_add_io(3), sd_event_add_time(3), sd_event_add_signal(3),
200 sd_event_add_inotify(3), sd_event_add_defer(3),
201 sd_event_source_set_enabled(3), sd_event_source_set_priority(3),
202 sd_event_source_set_userdata(3), sd_event_source_set_description(3),
203 sd_event_source_set_floating(3), waitid(2), sigprocmask(2),
204 pthread_sigmask(3), pidfd_open(2), pidfd_send_signal(2),
205 rt_sigqueueinfo(2), kill(2)
206systemd 246 SD_EVENT_ADD_CHILD(3)