Debian Codegraph @

upstream/debian-unstable/man3/sd_event_add_inotify.3

raw
1 '\" t
2 .TH "SD_EVENT_ADD_INOTIFY" "3" "" "systemd 261~rc3" "sd_event_add_inotify"
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_inotify, sd_event_add_inotify_fd, sd_event_source_get_inotify_mask, sd_event_source_get_inotify_path, sd_event_inotify_handler_t \- Add an "inotify" file system inode event source to an event loop
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-event\&.h>
29 .fi
30 .ft
31 .sp
32 .ft B
33 .nf
34 typedef struct sd_event_source sd_event_source;
35 .fi
36 .ft
37 .HP \w'typedef\ int\ (*sd_event_inotify_handler_t)('u
38 .BI "typedef int (*sd_event_inotify_handler_t)(sd_event_source\ *" "s" ", const\ struct\ inotify_event\ *" "event" ", void\ *" "userdata" ");"
39 .HP \w'int\ sd_event_add_inotify('u
40 .BI "int sd_event_add_inotify(sd_event\ *" "event" ", sd_event_source\ **" "source" ", const\ char\ *" "path" ", uint32_t\ " "mask" ", sd_event_inotify_handler_t\ " "handler" ", void\ *" "userdata" ");"
41 .HP \w'int\ sd_event_add_inotify_fd('u
42 .BI "int sd_event_add_inotify_fd(sd_event\ *" "event" ", sd_event_source\ **" "source" ", int\ " "fd" ", uint32_t\ " "mask" ", sd_event_inotify_handler_t\ " "handler" ", void\ *" "userdata" ");"
43 .HP \w'int\ sd_event_source_get_inotify_mask('u
44 .BI "int sd_event_source_get_inotify_mask(sd_event_source\ *" "source" ", uint32_t\ *" "ret" ");"
45 .HP \w'int\ sd_event_source_get_inotify_path('u
46 .BI "int sd_event_source_get_inotify_path(sd_event_source\ *" "source" ", const\ char\ **" "ret" ");"
47 .SH "DESCRIPTION"
48 .PP
49 \fBsd_event_add_inotify()\fR
50 adds a new
51 \fBinotify\fR(7)
52 file system inode event source to an event loop\&. The event loop object is specified in the
53 \fIevent\fR
54 parameter, the event source object is returned in the
55 \fIsource\fR
56 parameter\&. The
57 \fIpath\fR
58 parameter specifies the path of the file system inode to watch\&. The
59 \fImask\fR
60 parameter specifies which types of inode events to watch specifically\&. It must contain an OR\-ed combination of
61 \fBIN_ACCESS\fR,
62 \fBIN_ATTRIB\fR,
63 \fBIN_CLOSE_WRITE\fR, \&... flags\&. See
64 \fBinotify\fR(7)
65 for further information\&.
66 .PP
67 The
68 \fIhandler\fR
69 must reference a function to call when the inode changes or
70 \fBNULL\fR\&. The handler function will be passed the
71 \fIuserdata\fR
72 pointer, which may be chosen freely by the caller\&. The handler also receives a pointer to a
73 struct inotify_event
74 structure containing information about the inode event\&. The handler may return negative to signal an error (see below), other return values are ignored\&. If
75 \fIhandler\fR
76 is
77 \fBNULL\fR, a default handler that calls
78 \fBsd_event_exit\fR(3)
79 will be used\&.
80 .PP
81 \fBsd_event_add_inotify_fd()\fR
82 is identical to
83 \fBsd_event_add_inotify()\fR, except that it takes a file descriptor to an inode (possibly an
84 \fBO_PATH\fR
85 one, but any other will do too) instead of a path in the file system\&.
86 .PP
87 If multiple event sources are installed for the same inode the backing inotify watch descriptor is automatically shared\&. The mask parameter may contain any flag defined by the inotify API, with the exception of
88 \fBIN_MASK_ADD\fR\&.
89 .PP
90 The handler is enabled continuously (\fBSD_EVENT_ON\fR), but this may be changed with
91 \fBsd_event_source_set_enabled\fR(3)\&. Alternatively, the
92 \fBIN_ONESHOT\fR
93 mask flag may be used to request
94 \fBSD_EVENT_ONESHOT\fR
95 mode\&. If the handler function returns a negative error code, it will be disabled after the invocation, even if the
96 \fBSD_EVENT_ON\fR
97 mode was requested before\&.
98 .PP
99 As a special limitation the priority of inotify event sources may only be altered (see
100 \fBsd_event_source_set_priority\fR(3)) in the time between creation of the event source object with
101 \fBsd_event_add_inotify()\fR
102 and the beginning of the next event loop iteration\&. Attempts of changing the priority any later will be refused\&. Consider freeing and allocating a new inotify event source to change the priority at that point\&.
103 .PP
104 To destroy an event source object use
105 \fBsd_event_source_unref\fR(3), 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\*(Aqs still a reference to it kept, consider disabling it with
106 \fBsd_event_source_set_enabled\fR(3)\&.
107 .PP
108 If the second parameter of
109 \fBsd_event_add_inotify()\fR
110 is passed as
111 \fBNULL\fR
112 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\&.
113 .PP
114 If the
115 \fIhandler\fR
116 parameter to
117 \fBsd_event_add_inotify()\fR
118 is
119 \fBNULL\fR, and the event source fires, this will be considered a request to exit the event loop\&. In this case, the
120 \fIuserdata\fR
121 parameter, cast to an integer, is passed as the exit code parameter to
122 \fBsd_event_exit\fR(3)\&.
123 .PP
124 \fBsd_event_source_get_inotify_mask()\fR
125 retrieves the configured inotify watch mask of an event source created previously with
126 \fBsd_event_add_inotify()\fR\&. It takes the event source object as the
127 \fIsource\fR
128 parameter and a pointer to a
129 \fBuint32_t\fR
130 variable to return the mask in\&.
131 .PP
132 \fBsd_event_source_get_inotify_path()\fR
133 retrieves the target path of the configured inotify watch of an event source created previously with
134 \fBsd_event_add_inotify()\fR\&. It takes the event source object as the
135 \fIsource\fR
136 parameter and a pointer to a
137 \fBconst char **\fR
138 variable to return the path in\&. The caller must not free the returned path\&.
139 .SH "RETURN VALUE"
140 .PP
141 On success, these functions return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
142 .SS "Errors"
143 .PP
144 Returned errors may indicate the following problems:
145 .PP
146 \fB\-ENOMEM\fR
147 .RS 4
148 Not enough memory to allocate an object\&.
149 .RE
150 .PP
151 \fB\-EINVAL\fR
152 .RS 4
153 An invalid argument has been passed\&. This includes specifying a mask with
154 \fBIN_MASK_ADD\fR
155 set\&.
156 .RE
157 .PP
158 \fB\-ESTALE\fR
159 .RS 4
160 Returned by
161 \fBsd_event_source_add_inotify()\fR
162 or
163 \fBsd_event_source_add_inotify_fd()\fR
164 when the event loop is already terminated\&. Returned by
165 \fBsd_event_source_get_inotify_path()\fR
166 when no active inode data is assigned to the event source, e\&.g\&. when the event source is disabled\&.
167 .RE
168 .PP
169 \fB\-ECHILD\fR
170 .RS 4
171 The event loop has been created in a different process, library or module instance\&.
172 .RE
173 .PP
174 \fB\-EDOM\fR
175 .RS 4
176 The passed event source is not an inotify process event source\&.
177 .RE
178 .PP
179 \fB\-EBADF\fR
180 .RS 4
181 The passed file descriptor is not valid\&.
182 .RE
183 .PP
184 \fB\-ENOSYS\fR
185 .RS 4
186 \fBsd_event_add_inotify_fd()\fR
187 or
188 \fBsd_event_source_get_inotify_path()\fR
189 was called without
190 /proc/
191 mounted\&.
192 .RE
193 .SH "EXAMPLES"
194 .PP
195 \fBExample\ \&1.\ \&A simple program that uses inotify to monitor one or two directories\fR
196 .sp
197 .if n \{\
198 .RS 4
199 .\}
200 .nf
201 /* SPDX\-License\-Identifier: MIT\-0 */
202
203 #include <stdio\&.h>
204 #include <string\&.h>
205 #include <sys/inotify\&.h>
206
207 #include <systemd/sd\-event\&.h>
208
209 #define _cleanup_(f) __attribute__((cleanup(f)))
210
211 static int inotify_handler(sd_event_source *source,
212 const struct inotify_event *event,
213 void *userdata) {
214
215 const char *desc = NULL;
216
217 sd_event_source_get_description(source, &desc);
218
219 if (event\->mask & IN_Q_OVERFLOW)
220 printf("inotify\-handler <%s>: overflow\en", desc);
221 else if (event\->mask & IN_CREATE)
222 printf("inotify\-handler <%s>: create on %s\en", desc, event\->name);
223 else if (event\->mask & IN_DELETE)
224 printf("inotify\-handler <%s>: delete on %s\en", desc, event\->name);
225 else if (event\->mask & IN_MOVED_TO)
226 printf("inotify\-handler <%s>: moved\-to on %s\en", desc, event\->name);
227
228 /* Terminate the program if an "exit" file appears */
229 if ((event\->mask & (IN_CREATE|IN_MOVED_TO)) &&
230 strcmp(event\->name, "exit") == 0)
231 sd_event_exit(sd_event_source_get_event(source), 0);
232
233 return 1;
234 }
235
236 int main(int argc, char **argv) {
237 _cleanup_(sd_event_unrefp) sd_event *event = NULL;
238 _cleanup_(sd_event_source_unrefp) sd_event_source *source1 = NULL, *source2 = NULL;
239
240 const char *path1 = argc > 1 ? argv[1] : "/tmp";
241 const char *path2 = argc > 2 ? argv[2] : NULL;
242
243 /* Note: failure handling is omitted for brevity */
244
245 sd_event_default(&event);
246
247 sd_event_add_inotify(event, &source1, path1,
248 IN_CREATE | IN_DELETE | IN_MODIFY | IN_MOVED_TO,
249 inotify_handler, NULL);
250 if (path2)
251 sd_event_add_inotify(event, &source2, path2,
252 IN_CREATE | IN_DELETE | IN_MODIFY | IN_MOVED_TO,
253 inotify_handler, NULL);
254
255 sd_event_loop(event);
256
257 return 0;
258 }
259 .fi
260 .if n \{\
261 .RE
262 .\}
263 .SH "NOTES"
264 .PP
265 Functions described here are available as a shared library, which can be compiled against and linked to with the
266 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
267 file\&.
268 .PP
269 The code described here uses
270 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
271 \fBsetenv\fR(3)
272 from a parallel thread\&. It is recommended to only do calls to
273 \fBsetenv()\fR
274 from an early phase of the program when no other threads have been started\&.
275 .SH "HISTORY"
276 .PP
277 \fBsd_event_inotify_handler_t()\fR,
278 \fBsd_event_add_inotify()\fR, and
279 \fBsd_event_source_get_inotify_mask()\fR
280 were added in version 239\&.
281 .PP
282 \fBsd_event_add_inotify_fd()\fR
283 was added in version 250\&.
284 .PP
285 \fBsd_event_source_get_inotify_path()\fR
286 was added in version 256\&.
287 .SH "SEE ALSO"
288 .PP
289 \fBsystemd\fR(1), \fBsd-event\fR(3), \fBsd_event_new\fR(3), \fBsd_event_now\fR(3), \fBsd_event_add_io\fR(3), \fBsd_event_add_time\fR(3), \fBsd_event_add_signal\fR(3), \fBsd_event_add_defer\fR(3), \fBsd_event_add_child\fR(3), \fBsd_event_source_set_enabled\fR(3), \fBsd_event_source_set_priority\fR(3), \fBsd_event_source_set_userdata\fR(3), \fBsd_event_source_set_description\fR(3), \fBsd_event_source_set_floating\fR(3), \fBwaitid\fR(2)