sd_event_add_child

Index · Directives · Python · libudev · gudev systemd 220

## Name

sd_event_add_child, sd_event_source_get_child_pid — Add a child state change event source to an event loop

## Synopsis

    #include <systemd/sd-bus.h>

`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`)`;

`typedef int (*sd_event_child_handler_t)(` | sd_event_source *s,
| const siginfo_t *si,
| void *userdata`)`;

`int sd_event_source_get_child_pid(` | sd_event_source *source,
| pid_t *pid`)`;

## Description

`sd_event_add_child()` adds a new child state change event source to an event loop object. The event loop is specified in `event`, the event source is returned in the `source` parameter. The `pid` parameter specifies 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 const siginfo_t structure containing the information about the 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 terminating), `WSTOPPED` (watch for the child being stopped by a signal), and `WCONTINUED` (watch for the child being resumed by a signal). See waitid(2) for further information.

Only a single handler may be installed for a specific child. The handler is enabled for a single event (`SD_EVENT_ONESHOT`), but this may be changed with sd_event_source_set_enabled(3). If the handler function returns a negative error code, it will be disabled after the invocation, even if `SD_EVENT_ON` mode is set.

`sd_event_source_get_child_pid()` retrieves the configured `pid` of a child 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 pid_t to return the result in.

## 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`

  An handler is already installed for this child.

`-ESTALE`

  The event loop is already terminated.

`-ECHILD`

  The event loop has been created in a different process.

## Notes

`sd_event_add_child()` and the other functions described here are available as a shared library, which can be compiled and linked to with the `libsystemd` pkg-config(1) file.

## See Also

systemd(1), sd-event(3), sd_event_new(3), sd_event_add_time(3), sd_event_add_signal(3), sd_event_add_defer(3), sd_event_source_set_enabled(3)