sd_event_child_handler_t(3)

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 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
101       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
108       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
120       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
126       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
137       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
147       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
158       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

RETURN VALUE

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

NOTES

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

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO