]>
Commit | Line | Data |
---|---|---|
5eef597e | 1 | '\" t |
f47781d8 | 2 | .TH "SD_EVENT_ADD_CHILD" "3" "" "systemd 218" "sd_event_add_child" |
5eef597e MP |
3 | .\" ----------------------------------------------------------------- |
4 | .\" * Define some portability stuff | |
5 | .\" ----------------------------------------------------------------- | |
6 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7 | .\" http://bugs.debian.org/507673 | |
8 | .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html | |
9 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
10 | .ie \n(.g .ds Aq \(aq | |
11 | .el .ds Aq ' | |
12 | .\" ----------------------------------------------------------------- | |
13 | .\" * set default formatting | |
14 | .\" ----------------------------------------------------------------- | |
15 | .\" disable hyphenation | |
16 | .nh | |
17 | .\" disable justification (adjust text to left margin only) | |
18 | .ad l | |
19 | .\" ----------------------------------------------------------------- | |
20 | .\" * MAIN CONTENT STARTS HERE * | |
21 | .\" ----------------------------------------------------------------- | |
22 | .SH "NAME" | |
23 | sd_event_add_child, sd_event_source_get_child_pid \- Add a child state change event source to an event loop | |
24 | .SH "SYNOPSIS" | |
25 | .sp | |
26 | .ft B | |
27 | .nf | |
28 | #include <systemd/sd\-bus\&.h> | |
29 | .fi | |
30 | .ft | |
31 | .HP \w'int\ sd_event_add_child('u | |
32 | .BI "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" ");" | |
33 | .HP \w'typedef\ int\ (*sd_event_child_handler_t)('u | |
34 | .BI "typedef int (*sd_event_child_handler_t)(sd_event_source\ *" "s" ", const\ siginfo_t\ *" "si" ", void\ *" "userdata" ");" | |
35 | .HP \w'int\ sd_event_source_get_child_pid('u | |
36 | .BI "int sd_event_source_get_child_pid(sd_event_source\ *" "source" ", pid_t\ *" "pid" ");" | |
37 | .SH "DESCRIPTION" | |
38 | .PP | |
39 | \fBsd_event_add_child()\fR | |
40 | adds a new child state change event source to an event loop object\&. The event loop is specified in | |
41 | \fIevent\fR, the event source is returned in the | |
42 | \fIsource\fR | |
43 | parameter\&. The | |
44 | \fIpid\fR | |
45 | parameter specifies the process to watch\&. The | |
46 | \fIhandler\fR | |
47 | must reference a function to call when the process changes state\&. The handler function will be passed the | |
48 | \fIuserdata\fR | |
49 | pointer, which may be chosen freely by the caller\&. The handler also receives a pointer to a | |
50 | const siginfo_t | |
51 | structure containing the information about the event\&. The | |
52 | \fIoptions\fR | |
53 | parameter determines which state changes will be watched for\&. It must contain an OR\-ed mask of | |
54 | \fBWEXITED\fR | |
55 | (watch for the child terminating), | |
56 | \fBWSTOPPED\fR | |
57 | (watch for the child being stopped by a signal), and | |
58 | \fBWCONTINUED\fR | |
59 | (watch for the child being resumed by a signal)\&. See | |
60 | \fBwaitid\fR(2) | |
61 | for futher information\&. | |
62 | .PP | |
63 | Only a single handler may be installed for a specific child\&. The handler is enabled for a single event (\fBSD_EVENT_ONESHOT\fR), but this may be changed with | |
64 | \fBsd_event_source_set_enabled\fR(3)\&. If the handler function returns a negative error code, it will be disabled after the invocation, even if | |
65 | \fBSD_EVENT_ON\fR | |
66 | mode is set\&. | |
67 | .PP | |
68 | \fBsd_event_source_get_child_pid()\fR | |
69 | retrieves the configured | |
70 | \fIpid\fR | |
71 | of a child state change event source created previously with | |
72 | \fBsd_event_add_child()\fR\&. It takes the event source object as the | |
73 | \fIsource\fR | |
74 | parameter and a pointer to | |
75 | \fBpid_t\fR | |
76 | to return the result in\&. | |
77 | .SH "RETURN VALUE" | |
78 | .PP | |
79 | On success, these functions return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&. | |
80 | .SH "ERRORS" | |
81 | .PP | |
82 | Returned errors may indicate the following problems: | |
83 | .PP | |
84 | \fB\-ENOMEM\fR | |
85 | .RS 4 | |
86 | Not enough memory to allocate an object\&. | |
87 | .RE | |
88 | .PP | |
89 | \fB\-EINVAL\fR | |
90 | .RS 4 | |
91 | An invalid argument has been passed\&. This includes specyfing an empty mask in | |
92 | \fIoptions\fR | |
93 | or a mask which constains values different than a combination of | |
94 | \fBWEXITED\fR, | |
95 | \fBWSTOPPED\fR, and | |
96 | \fBWCONTINUED\fR\&. | |
97 | .RE | |
98 | .PP | |
99 | \fB\-EBUSY\fR | |
100 | .RS 4 | |
101 | An handler is already installed for this child\&. | |
102 | .RE | |
103 | .PP | |
104 | \fB\-ESTALE\fR | |
105 | .RS 4 | |
106 | The event loop is already terminated\&. | |
107 | .RE | |
108 | .PP | |
109 | \fB\-ECHILD\fR | |
110 | .RS 4 | |
111 | The event loop has been created in a different process\&. | |
112 | .RE | |
113 | .SH "NOTES" | |
114 | .PP | |
115 | \fBsd_event_add_child()\fR | |
116 | and the other functions described here are available as a shared library, which can be compiled and linked to with the | |
117 | \fBlibsystemd\fR\ \&\fBpkg-config\fR(1) | |
118 | file\&. | |
119 | .SH "SEE ALSO" | |
120 | .PP | |
121 | \fBsystemd\fR(1), | |
122 | \fBsd-event\fR(3), | |
123 | \fBsd_event_new\fR(3), | |
124 | \fBsd_event_add_time\fR(3), | |
125 | \fBsd_event_add_signal\fR(3), | |
126 | \fBsd_event_add_defer\fR(3), | |
127 | \fBsd_event_source_set_enabled\fR(3) |