sd_event_add

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.