diff --git a/man/rules/meson.build b/man/rules/meson.build index 20c3d09da0..0f6897a080 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -371,7 +371,15 @@ manpages = [ ['sd_bus_wait', '3', [], ''], ['sd_event_add_child', '3', - ['sd_event_child_handler_t', 'sd_event_source_get_child_pid'], + ['sd_event_add_child_pidfd', + 'sd_event_child_handler_t', + 'sd_event_source_get_child_pid', + 'sd_event_source_get_child_pidfd', + 'sd_event_source_get_child_pidfd_own', + 'sd_event_source_get_child_process_own', + 'sd_event_source_send_child_signal', + 'sd_event_source_set_child_pidfd_own', + 'sd_event_source_set_child_process_own'], ''], ['sd_event_add_defer', '3', diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml index c146e3121b..1db536ff2a 100644 --- a/man/sd_event_add_child.xml +++ b/man/sd_event_add_child.xml @@ -17,7 +17,14 @@ 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 @@ -46,40 +53,77 @@ 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. The handler must - reference a function to call when the process changes state. 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 - 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. + 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 handler must reference a function to call when the process changes + state. 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 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. Only a single handler may be installed for a specific child process. The handler is enabled for a single event @@ -127,6 +171,17 @@ 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 @@ -135,6 +190,45 @@ 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. @@ -196,6 +290,12 @@ The passed event source is not a child process event source. + + -EOPNOTSUPP + + A pidfd was requested but the kernel does not support this concept. + + @@ -222,7 +322,11 @@ sd_event_source_set_floating3, waitid2, sigprocmask2, - pthread_sigmask3 + pthread_sigmask3, + pidfd_open2, + pidfd_send_signal2, + rt_sigqueueinfo2, + kill2