Movatterモバイル変換

sd_event_add_child(3) — Linux manual page

SD_EVENT_ADD_CHILD(3)       sd_event_add_childSD_EVENT_ADD_CHILD(3)

NAME        top

       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

SYNOPSIS        top

#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_tpid, intoptions,sd_event_child_handler_thandler,void *userdata);int sd_event_add_child_pidfd(sd_event *event,sd_event_source **source, intpidfd,intoptions,sd_event_child_handler_thandler,void *userdata);int sd_event_source_get_child_pid(sd_event_source *source,pid_t *ret);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,intown);intsd_event_source_get_child_process_own(sd_event_source *source);int sd_event_source_set_child_process_own(sd_event_source *source,intown);int sd_event_source_send_child_signal(sd_event_source *source,intsig,const siginfo_t *info,unsignedflags);

DESCRIPTION        top

sd_event_add_child()adds a new child process state change event       source to an event loop. The event loop object is specified in theevent parameter, the event source object is returned in thesource       parameter. Thepid parameter specifies the PID of the process to       watch, which must be a direct child process of the invoking       process. Theoptions parameter determines which state changes will       be watched for. It must contain an OR-ed mask ofWEXITED(watch       for the child process terminating),WSTOPPED(watch for the child       process being stopped by a signal), andWCONTINUED(watch for the       child process being resumed by a signal). Seewaitid(2) for       further information.       Thehandler must be a function to call when the process changes       state orNULL. The handler function will be passed theuserdata       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. Ifhandler isNULL, a default handler that callssd_event_exit(3) 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 withsd_event_source_set_enabled(3). If the handler function returns a       negative error code, it will either be disabled after the       invocation, even if theSD_EVENT_ONmode was requested before, or       it will cause the loop to terminate, seesd_event_source_set_exit_on_failure(3).       To destroy an event source object usesd_event_source_unref(3),       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 toSD_EVENT_OFFwithsd_event_source_set_enabled(3).       TheSIGCHLDsignal must be blocked in all threads before this       function is called (usingsigprocmask(2) orpthread_sigmask(3)).       If the second parameter ofsd_event_add_child()is passed asNULL       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 thehandler 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 thehandler parameter tosd_event_add_child()isNULL, and the       event source fires, this will be considered a request to exit the       event loop. In this case, theuserdata parameter, cast to an       integer, is passed as the exit code parameter tosd_event_exit(3).       If both a child process state change event source and aSIGCHLD       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 tosd_event_add_child()but       takes a file descriptor referencing the process ("pidfd") instead       of the numeric PID. A suitable file descriptor may be acquired viapidfd_open(2) and related calls. The passed file descriptor is not       closed when the event source is freed again, unlesssd_event_source_set_child_pidfd_own()is used to turn this       behaviour on. Note that regardless which ofsd_event_add_child()       andsd_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 casesSIGCHLDhas 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 withsd_event_add_child(). It takes the event source object as thesource parameter and a pointer to apid_tvariable to return the       process ID in.sd_event_source_get_child_pidfd()retrieves the file descriptor       referencing the watched process ("pidfd"). The event loop       internally makes use of pidfds to watch child processes,       regardless of whether the individual event sources are allocated       viasd_event_add_child()orsd_event_add_child_pidfd(). If the       latter call was used to allocate the event source, this function       returns the original file descriptor used for allocation. This       call takes the event source object as thesource 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 viasd_event_add_child()and off if it       was allocated viasd_event_add_child_pidfd(). Thesd_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 (withSIGKILL) 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. Thesd_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 viapidfd_send_signal(2). The       specified parameters match those of the underlying system call,       except that theinfo is never modified (and is thus declared       constant). Like for the underlying system call, theflags       parameter currently must be zero.

RETURN VALUE        top

       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 inoptions or a mask which contains values           different than a combination ofWEXITED,WSTOPPED, andWCONTINUED.-EBUSY           A handler is already installed for this child process, orSIGCHLDis not blocked.-ESTALE           The event loop is already terminated.-ECHILD           The event loop has been created in a different process,           library or module instance.-EDOM           The passed event source is not a child process event source.

NOTES        top

       Functions described here are available as a shared library, which       can be compiled against and linked to with thelibsystemd pkg-config(1) file.       The code described here usesgetenv(3), which is declared to be       not multi-thread-safe. This means that the code calling the       functions described here must not callsetenv(3) from a parallel       thread. It is recommended to only do calls tosetenv()from an       early phase of the program when no other threads have been       started.

EXAMPLE        top

Example 1. Exit loop when the child terminates           /* SPDX-License-Identifier: MIT-0 */           #define _GNU_SOURCE 1           #include <assert.h>           #include <stdio.h>           #include <unistd.h>           #include <systemd/sd-event.h>           int main(int argc, char **argv) {             pid_t pid = fork();             assert(pid >= 0);             /* SIGCHLD signal must be blocked for sd_event_add_child to work */             sigset_t ss;             sigemptyset(&ss);             sigaddset(&ss, SIGCHLD);             sigprocmask(SIG_BLOCK, &ss, NULL);             if (pid == 0)  /* child */               sleep(1);             else {         /* parent */               sd_event *e = NULL;               int r;               /* Create the default event loop */               sd_event_default(&e);               assert(e);               /* We create a floating child event source (attached to 'e').                * The default handler will be called with 666 as userdata, which                * will become the exit value of the loop. */               r = sd_event_add_child(e, NULL, pid, WEXITED, NULL, (void*) 666);               assert(r >= 0);               r = sd_event_loop(e);               assert(r == 666);               sd_event_unref(e);             }             return 0;           }

HISTORY        top

sd_event_add_child(),sd_event_child_handler_t(), andsd_event_source_get_child_pid()were added in version 217.sd_event_add_child_pidfd(),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(), andsd_event_source_send_child_signal()were added in version 245.

SEE ALSO        top

systemd(1),sd-event(3),sd_event_new(3),sd_event_now(3),sd_event_add_io(3),sd_event_add_time(3),sd_event_add_signal(3),sd_event_add_inotify(3),sd_event_add_defer(3),sd_event_source_set_enabled(3),sd_event_source_set_priority(3),sd_event_source_set_userdata(3),sd_event_source_set_description(3),sd_event_source_set_floating(3),waitid(2),sigprocmask(2),pthread_sigmask(3),pidfd_open(2),pidfd_send_signal(2),rt_sigqueueinfo(2),kill(2)

COLOPHON        top

       This page is part of thesystemd (systemd system and service       manager) project.  Information about the project can be found at       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have a       bug report for this manual page, see       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.       This page was obtained from the project's upstream Git repository       ⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11.  (At that       time, the date of the most recent commit that was found in the       repository was 2025-08-11.)  If you discover any rendering       problems in this HTML version of the page, or you believe there is       a better or more up-to-date source for the page, or you have       corrections or improvements to the information in this COLOPHON       (which isnot part of the original manual page), send a mail to       man-pages@man7.orgsystemd 258~rc2SD_EVENT_ADD_CHILD(3)

Pages that refer to this page:sd-event(3), sd_event_add_defer(3), sd_event_add_inotify(3), sd_event_add_io(3), sd_event_add_memory_pressure(3), sd_event_add_signal(3), sd_event_add_time(3), sd_event_new(3), sd_event_run(3), sd_event_set_watchdog(3), sd_event_source_get_event(3), sd_event_source_get_pending(3), sd_event_source_set_description(3), sd_event_source_set_destroy_callback(3), sd_event_source_set_enabled(3), sd_event_source_set_exit_on_failure(3), sd_event_source_set_floating(3), sd_event_source_set_prepare(3), sd_event_source_set_priority(3), sd_event_source_set_userdata(3), sd_event_source_unref(3), sd_event_wait(3), systemd.directives(7), systemd.index(7)

HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH.