From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/sd_event_add_child.xml | 352 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 man/sd_event_add_child.xml (limited to 'man/sd_event_add_child.xml') diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml new file mode 100644 index 0000000..fec754d --- /dev/null +++ b/man/sd_event_add_child.xml @@ -0,0 +1,352 @@ + + + + + + + + sd_event_add_child + systemd + + + + sd_event_add_child + 3 + + + + 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 + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_child_handler_t) + sd_event_source *s + const siginfo_t *si + void *userdata + + + + 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 + + + + 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 + + + + int sd_event_source_get_child_pid + sd_event_source *source + pid_t *pid + + + + int sd_event_source_get_child_pidfd + sd_event_source *source + + + + int sd_event_source_get_child_pidfd_own + sd_event_source *source + + + + int sd_event_source_set_child_pidfd_own + sd_event_source *source + int own + + + + int sd_event_source_get_child_process_own + sd_event_source *source + + + + int sd_event_source_set_child_process_own + sd_event_source *source + int own + + + + int sd_event_source_send_child_signal + sd_event_source *source + int sig + const siginfo_t *info + unsigned flags + + + + + + + Description + + sd_event_add_child() adds a new child process state change event source to an + event loop. The event loop object is specified in the event parameter, the event + source object is returned in the source parameter. The pid + parameter specifies the PID of the process to watch, which must be a direct child process of the invoking + process. The options parameter determines which state changes will be watched for. + It must contain an OR-ed mask of WEXITED (watch for the child process terminating), + WSTOPPED (watch for the child process being stopped by a signal), and + WCONTINUED (watch for the child process being resumed by a signal). See + waitid2 + for further information. + + The handler must be a function to call when the process changes state or + NULL. The handler function will be passed the userdata + pointer, which may be chosen freely by the caller. The handler also receives a pointer to a + siginfo_t 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 + handler is NULL, a default handler that calls + sd_event_exit3 will be + used. + + Only a single handler may be installed for a specific child process. The handler is enabled for a + single event (SD_EVENT_ONESHOT), but this may be changed with + sd_event_source_set_enabled3. + If the handler function returns a negative error code, it will either be disabled after the invocation, + even if the SD_EVENT_ON mode was requested before, or it will cause the loop to + terminate, see + sd_event_source_set_exit_on_failure3. + + + To destroy an event source object use + sd_event_source_unref3, + 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's still a + reference to it kept, consider setting the event source to + SD_EVENT_OFF with + sd_event_source_set_enabled3. + + The SIGCHLD signal must be blocked in all threads before this function is + called (using sigprocmask2 or + pthread_sigmask3). + + If the second parameter of sd_event_add_child() is passed as + NULL 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. + + Note that the handler 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. + + If the handler parameter to sd_event_add_child() is + NULL, and the event source fires, this will be considered a request to exit the + event loop. In this case, the userdata parameter, cast to an integer, is passed as + the exit code parameter to + sd_event_exit3. + + If both a child process state change event source and a + SIGCHLD 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. + + sd_event_add_child_pidfd() is similar to + sd_event_add_child() but takes a file descriptor referencing the process ("pidfd") + instead of the numeric PID. A suitable file descriptor may be acquired via pidfd_open2 and + related calls. The passed file descriptor is not closed when the event source is freed again, unless + sd_event_source_set_child_pidfd_own() is used to turn this behaviour on. Note that + regardless which of sd_event_add_child() and + sd_event_add_child_pidfd() 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 + SIGCHLD has to be blocked in the invoking process. + + sd_event_source_get_child_pid() + retrieves the configured PID of a child process state change event + source created previously with + sd_event_add_child(). It takes the event + source object as the source parameter and a + pointer to a pid_t variable to return the process ID + in. + + + sd_event_source_get_child_pidfd() retrieves the file descriptor referencing + the watched process ("pidfd") if this functionality is available. On kernels that support the concept the + event loop will make use of pidfds to watch child processes, regardless if the individual event sources + are allocated via sd_event_add_child() or + sd_event_add_child_pidfd(). If the latter call was used to allocate the event + source, this function returns the file descriptor used for allocation. On kernels that do not support the + pidfd concept this function will fail with EOPNOTSUPP. This call takes the event + source object as the source parameter and returns the numeric file descriptor. + + + sd_event_source_get_child_pidfd_own() 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 sd_event_add_child() + and off if it was allocated via sd_event_add_child_pidfd(). The + sd_event_source_set_child_pidfd_own() function may be used to change the setting and + takes a boolean parameter with the new setting. + + sd_event_source_get_child_process_own() may be used to query whether the + process the event source watches shall be killed (with SIGKILL) 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 + sd_event_source_set_child_process_own() 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. + + sd_event_source_send_child_signal() may be used to send a UNIX signal to the + watched process. If the pidfd concept is supported in the kernel, this is implemented via pidfd_send_signal2 + and otherwise via rt_sigqueueinfo2 + (or via kill2 in case + info is NULL). The specified parameters match those of these + underlying system calls, except that the info is never modified (and is thus + declared constant). Like for the underlying system calls, the flags parameter + currently must be zero. + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. This includes + specifying an empty mask in options or a mask + which contains values different than a combination of + WEXITED, WSTOPPED, and + WCONTINUED. + + + + + + -EBUSY + + A handler is already installed for this child process, or + SIGCHLD is not blocked. + + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -EDOM + + The passed event source is not a child process event source. + + + + -EOPNOTSUPP + + A pidfd was requested but the kernel does not support this concept. + + + + + + + + + + Example + + + Exit loop when the child terminates + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_inotify3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + sd_event_source_set_floating3, + waitid2, + sigprocmask2, + pthread_sigmask3, + pidfd_open2, + pidfd_send_signal2, + rt_sigqueueinfo2, + kill2 + + + + -- cgit v1.2.3