X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;ds=inline;f=man%2Fsd_event_add_child.xml;fp=man%2Fsd_event_add_child.xml;h=1e7cbf56eb1264f66930594ca019c29df162c73b;hb=56c19a4f2a0091a3fe23712cbbc6c6e379572ffe;hp=0000000000000000000000000000000000000000;hpb=7873fa750d7d4310396e69df12b53e07e4e81249;p=elogind.git diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml new file mode 100644 index 000000000..1e7cbf56e --- /dev/null +++ b/man/sd_event_add_child.xml @@ -0,0 +1,246 @@ + + + + + + + + + sd_event_add_child + systemd + + + + More text + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_event_add_child + 3 + + + + sd_event_add_child + sd_event_source_get_child_pid + sd_event_child_handler_t + + Add a child process state change event source to an event loop + + + + + #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_t pid + int options + sd_event_child_handler_t handler + 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 + 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. + + 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 + with + sd_event_source_set_enabled3. + If the handler function returns a negative error code, it will be + 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 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 a pid_t variable to return the process ID + 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 + + A handler is already installed for this + child process. + + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -EDOM + + The passed event source is not a child process event source. + + + + + + + + + See Also + + + 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_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + waitid2 + + + +