1SD_EVENT_ADD_CHILD(3)         sd_event_add_child         SD_EVENT_ADD_CHILD(3)
2
3
4

NAME

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

SYNOPSIS

16       #include <systemd/sd-event.h>
17
18       typedef struct sd_event_source sd_event_source;
19
20       typedef int (*sd_event_child_handler_t)(sd_event_source *s,
21                                               const siginfo_t *si,
22                                               void *userdata);
23
24       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
29       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
34       int sd_event_source_get_child_pid(sd_event_source *source, pid_t *pid);
35
36       int sd_event_source_get_child_pidfd(sd_event_source *source);
37
38       int sd_event_source_get_child_pidfd_own(sd_event_source *source);
39
40       int sd_event_source_set_child_pidfd_own(sd_event_source *source,
41                                               int own);
42
43       int sd_event_source_get_child_process_own(sd_event_source *source);
44
45       int sd_event_source_set_child_process_own(sd_event_source *source,
46                                                 int own);
47
48       int sd_event_source_send_child_signal(sd_event_source *source, int sig,
49                                             const siginfo_t *info,
50                                             unsigned flags);
51

DESCRIPTION

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
68       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
74       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
81       The SIGCHLD signal must be blocked in all threads before this function
82       is called (using sigprocmask(2) or pthread_sigmask(3)).
83
84       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
89       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
96       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
103       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
115       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
121       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
132       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
142       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
153       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

RETURN VALUE

163       On success, these functions return 0 or a positive integer. On failure,
164       they return a negative errno-style error code.
165
166   Errors
167       Returned errors may indicate the following problems:
168
169       -ENOMEM
170           Not enough memory to allocate an object.
171
172       -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
177       -EBUSY
178           A handler is already installed for this child process, or SIGCHLD
179           is not blocked.
180
181       -ESTALE
182           The event loop is already terminated.
183
184       -ECHILD
185           The event loop has been created in a different process.
186
187       -EDOM
188           The passed event source is not a child process event source.
189
190       -EOPNOTSUPP
191           A pidfd was requested but the kernel does not support this concept.
192

NOTES

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

SEE ALSO

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)
206
207
208
209systemd 245                                              SD_EVENT_ADD_CHILD(3)
Impressum