X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_event_add_child.xml;h=1e7cbf56eb1264f66930594ca019c29df162c73b;hp=012fdb6a1a84025d09558b758a3c41869d8e2b7a;hb=3ff66cca1cae924f9b6bd4dae3587dd854c77a16;hpb=8474b70c3a3842cdf3d51f331dd117ab6421f6d0 diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml index 012fdb6a1..1e7cbf56e 100644 --- a/man/sd_event_add_child.xml +++ b/man/sd_event_add_child.xml @@ -1,27 +1,27 @@ - + - + sd_event_add_child @@ -45,13 +45,23 @@ along with systemd; If not, see . sd_event_add_child sd_event_source_get_child_pid + sd_event_child_handler_t - Add a child state change event source to an event loop + Add a child process state change event source to an event loop - #include <systemd/sd-bus.h> + #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 @@ -63,13 +73,6 @@ along with systemd; If not, see . 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 @@ -83,42 +86,75 @@ along with systemd; If not, see . 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 + 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 - being stopped by a signal), and WCONTINUED - (watch for the child being resumed by a signal). See - waitid2 - for futher information. + 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. The handler is enabled - for a single event (SD_EVENT_ONESHOT), - but this may be - changed with + 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 be - disabled after the invocation, even if - SD_EVENT_ON mode is set. + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. + 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. + + 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 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_source_get_child_pid() - retrieves the configured pid of a child - state change event source created previously with + 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 pid_t to return the result in. + pointer to a pid_t variable to return the process ID + in. @@ -146,8 +182,8 @@ along with systemd; If not, see . -EINVAL An invalid argument has been passed. This includes - specyfing an empty mask in options or a mask - which constains values different than a combination of + specifying an empty mask in options or a mask + which contains values different than a combination of WEXITED, WSTOPPED, and WCONTINUED. @@ -157,8 +193,8 @@ along with systemd; If not, see . -EBUSY - An handler is already installed for this - child. + A handler is already installed for this + child process. @@ -176,19 +212,17 @@ along with systemd; If not, see . - - + + -EDOM - - Notes + The passed event source is not a child process event source. + - 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-config1 - file. + + + See Also @@ -196,10 +230,16 @@ along with systemd; If not, see . systemd1, sd-event3, sd_event_new3, + sd_event_now3, + sd_event_add_io3, sd_event_add_time3, sd_event_add_signal3, sd_event_add_defer3, - sd_event_source_set_enabled3 + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + waitid2