]>
Commit | Line | Data |
---|---|---|
4d2b74dd | 1 | '\" t |
415f63be | 2 | .\" Copyright (C) 2006, 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
4d2b74dd | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
4d2b74dd MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
4d2b74dd MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
10d76543 MK |
17 | .\" the use of the information contained herein. The author(s) may not |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
4d2b74dd MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
4d2b74dd | 25 | .\" |
356911f6 | 26 | .TH INOTIFY 7 2014-04-01 "Linux" "Linux Programmer's Manual" |
4d2b74dd | 27 | .SH NAME |
9ee4a2b6 | 28 | inotify \- monitoring filesystem events |
4d2b74dd MK |
29 | .SH DESCRIPTION |
30 | The | |
c13182ef | 31 | .I inotify |
9ee4a2b6 | 32 | API provides a mechanism for monitoring filesystem events. |
4d2b74dd MK |
33 | Inotify can be used to monitor individual files, |
34 | or to monitor directories. | |
35 | When a directory is monitored, inotify will return events | |
36 | for the directory itself, and for files inside the directory. | |
37 | ||
c13182ef | 38 | The following system calls are used with this API: |
356911f6 | 39 | .IP * 3 |
4d2b74dd | 40 | .BR inotify_init (2) |
c13182ef | 41 | creates an inotify instance and returns a file descriptor |
a2cc46ca | 42 | referring to the inotify instance. |
43bb5faf MK |
43 | The more recent |
44 | .BR inotify_init1 (2) | |
45 | is like | |
46 | .BR inotify_init (2), | |
356911f6 MK |
47 | but has a |
48 | .IR flags | |
49 | argument that provides access to some extra functionality. | |
50 | .IP * | |
4d2b74dd | 51 | .BR inotify_add_watch (2) |
a2cc46ca | 52 | manipulates the "watch list" associated with an inotify instance. |
3a065ac0 | 53 | Each item ("watch") in the watch list specifies the pathname of |
c13182ef | 54 | a file or directory, |
4d2b74dd MK |
55 | along with some set of events that the kernel should monitor for the |
56 | file referred to by that pathname. | |
63f6a20a | 57 | .BR inotify_add_watch (2) |
4d2b74dd MK |
58 | either creates a new watch item, or modifies an existing watch. |
59 | Each watch has a unique "watch descriptor", an integer | |
60 | returned by | |
63f6a20a | 61 | .BR inotify_add_watch (2) |
4d2b74dd | 62 | when the watch is created. |
356911f6 MK |
63 | .IP * |
64 | When events occur for monitored files and directories, | |
65 | those events are made available to the application as structured data that | |
66 | can be read from the inotify file descriptor using | |
67 | .BR read (2) | |
68 | (see below). | |
69 | .IP * | |
4d2b74dd MK |
70 | .BR inotify_rm_watch (2) |
71 | removes an item from an inotify watch list. | |
356911f6 | 72 | .IP * |
c13182ef | 73 | When all file descriptors referring to an inotify |
356911f6 MK |
74 | instance have been closed (using |
75 | .BR close (2)), | |
c13182ef | 76 | the underlying object and its resources are |
3b777aff | 77 | freed for reuse by the kernel; |
4d2b74dd | 78 | all associated watches are automatically freed. |
ff6e2397 | 79 | .SS Reading events from an inotify file descriptor |
4d2b74dd MK |
80 | To determine what events have occurred, an application |
81 | .BR read (2)s | |
82 | from the inotify file descriptor. | |
c13182ef | 83 | If no events have so far occurred, then, |
11da88fb | 84 | assuming a blocking file descriptor, |
63f6a20a | 85 | .BR read (2) |
01538d0d MK |
86 | will block until at least one event occurs |
87 | (unless interrupted by a signal, | |
88 | in which case the call fails with the error | |
89 | .BR EINTR ; | |
90 | see | |
91 | .BR signal (7)). | |
4d2b74dd MK |
92 | |
93 | Each successful | |
63f6a20a | 94 | .BR read (2) |
4d2b74dd | 95 | returns a buffer containing one or more of the following structures: |
a08ea57c | 96 | .in +4n |
4d2b74dd MK |
97 | .nf |
98 | ||
99 | struct inotify_event { | |
100 | int wd; /* Watch descriptor */ | |
24bbe02c MK |
101 | .\" FIXME . The type of the 'wd' field should probably be "int32_t". |
102 | .\" I submitted a patch to fix this. See the LKML thread | |
103 | .\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008 | |
6e6231c1 | 104 | .\" Glibc bug filed: http://sources.redhat.com/bugzilla/show_bug.cgi?id=7040 |
4d2b74dd | 105 | uint32_t mask; /* Mask of events */ |
c13182ef | 106 | uint32_t cookie; /* Unique cookie associating related |
4d2b74dd | 107 | events (for rename(2)) */ |
84c517a4 | 108 | uint32_t len; /* Size of \fIname\fP field */ |
4d2b74dd MK |
109 | char name[]; /* Optional null-terminated name */ |
110 | }; | |
111 | .fi | |
a08ea57c | 112 | .in |
4d2b74dd MK |
113 | |
114 | .I wd | |
115 | identifies the watch for which this event occurs. | |
c13182ef | 116 | It is one of the watch descriptors returned by a previous call to |
63f6a20a | 117 | .BR inotify_add_watch (2). |
4d2b74dd MK |
118 | |
119 | .I mask | |
120 | contains bits that describe the event that occurred (see below). | |
121 | ||
122 | .I cookie | |
123 | is a unique integer that connects related events. | |
33a0ccb2 | 124 | Currently this is used only for rename events, and |
4d2b74dd | 125 | allows the resulting pair of |
bc636d8a | 126 | .B IN_MOVED_FROM |
c13182ef | 127 | and |
bc636d8a | 128 | .B IN_MOVED_TO |
4d2b74dd | 129 | events to be connected by the application. |
591b7a5f MK |
130 | For all other event types, |
131 | .I cookie | |
132 | is set to 0. | |
4d2b74dd | 133 | |
c13182ef | 134 | The |
4d2b74dd | 135 | .I name |
33a0ccb2 | 136 | field is present only when an event is returned |
c13182ef | 137 | for a file inside a watched directory; |
4d2b74dd | 138 | it identifies the file pathname relative to the watched directory. |
c13182ef | 139 | This pathname is null-terminated, |
1aff5804 | 140 | and may include further null bytes (\(aq\\0\(aq) to align subsequent reads to a |
4d2b74dd MK |
141 | suitable address boundary. |
142 | ||
143 | The | |
144 | .I len | |
c13182ef | 145 | field counts all of the bytes in |
4d2b74dd | 146 | .IR name , |
c13182ef | 147 | including the null bytes; |
4d2b74dd MK |
148 | the length of each |
149 | .I inotify_event | |
150 | structure is thus | |
655684a9 | 151 | .IR "sizeof(struct inotify_event)+len" . |
c7e3ee6f | 152 | |
988db661 | 153 | The behavior when the buffer given to |
c7e3ee6f | 154 | .BR read (2) |
988db661 | 155 | is too small to return information about the next event depends |
c7e3ee6f MK |
156 | on the kernel version: in kernels before 2.6.21, |
157 | .BR read (2) | |
158 | returns 0; since kernel 2.6.21, | |
159 | .BR read (2) | |
160 | fails with the error | |
161 | .BR EINVAL . | |
4ba272b3 MK |
162 | Specifying a buffer of size |
163 | ||
164 | sizeof(struct inotify_event) + NAME_MAX + 1 | |
165 | ||
166 | will be sufficient to read at least one event. | |
4d2b74dd | 167 | .SS inotify events |
c13182ef | 168 | The |
4d2b74dd MK |
169 | .BR inotify_add_watch (2) |
170 | .I mask | |
c13182ef | 171 | argument and the |
4d2b74dd MK |
172 | .I mask |
173 | field of the | |
174 | .I inotify_event | |
175 | structure returned when | |
176 | .BR read (2)ing | |
177 | an inotify file descriptor are both bit masks identifying | |
178 | inotify events. | |
179 | The following bits can be specified in | |
180 | .I mask | |
181 | when calling | |
63f6a20a | 182 | .BR inotify_add_watch (2) |
c13182ef | 183 | and may be returned in the |
4d2b74dd MK |
184 | .I mask |
185 | field returned by | |
63f6a20a | 186 | .BR read (2): |
64aa9bcb | 187 | .RS 4 |
c577b95c | 188 | .TP |
f23fc716 | 189 | .BR IN_ACCESS " (*)" |
70f70c9d MK |
190 | File was accessed (e.g., |
191 | .BR read (2), | |
f23fc716 | 192 | .BR execve (2)). |
3f174f7d | 193 | .TP |
f23fc716 | 194 | .BR IN_ATTRIB " (*)" |
b0e1ac43 MK |
195 | Metadata changed\(emfor example, permissions (e.g., |
196 | .BR chmod (2)), | |
197 | timestamps (e.g., | |
198 | .BR utimensat (2)), | |
199 | extended attributes | |
200 | .RB ( setxattr (2)), | |
201 | link count (since Linux 2.6.25; e.g., | |
202 | for the target of | |
203 | .BR link (2) | |
204 | and for | |
205 | .BR unlink (2)), | |
206 | and user/group ID (e.g., | |
207 | .BR chown (2)). | |
3f174f7d | 208 | .TP |
f23fc716 MK |
209 | .BR IN_CLOSE_WRITE " (*)" |
210 | File opened for writing was closed. | |
3f174f7d | 211 | .TP |
f23fc716 MK |
212 | .BR IN_CLOSE_NOWRITE " (*)" |
213 | File not opened for writing was closed. | |
3f174f7d | 214 | .TP |
f23fc716 | 215 | .BR IN_CREATE " (*)" |
7a64793b MK |
216 | File/directory created in watched directory (e.g., |
217 | .BR open (2) | |
218 | .BR O_CREAT , | |
219 | .BR mkdir (2), | |
220 | .BR link (2), | |
1a737afd | 221 | .BR symlink (2), |
7a64793b MK |
222 | .BR bind (2) |
223 | on a UNIX domain socket). | |
3f174f7d | 224 | .TP |
f23fc716 MK |
225 | .BR IN_DELETE " (*)" |
226 | File/directory deleted from watched directory. | |
3f174f7d MK |
227 | .TP |
228 | .B IN_DELETE_SELF | |
229 | Watched file/directory was itself deleted. | |
4a1e4cca MK |
230 | (This event also occurs if an object is moved to another filesystem, |
231 | since | |
232 | .BR mv (1) | |
233 | in effect copies the file to the other filesystem and | |
49b07b8f | 234 | then deletes it from the original filesystem.) |
39f43968 MK |
235 | In addition, an |
236 | .B IN_IGNORED | |
237 | event will subsequently be generated for the watch descriptor. | |
3f174f7d | 238 | .TP |
f23fc716 | 239 | .BR IN_MODIFY " (*)" |
f54a1255 MK |
240 | File was modified (e.g., |
241 | .BR write (2), | |
242 | .BR truncate (2)). | |
3f174f7d MK |
243 | .TP |
244 | .B IN_MOVE_SELF | |
245 | Watched file/directory was itself moved. | |
246 | .TP | |
f23fc716 | 247 | .BR IN_MOVED_FROM " (*)" |
107375cf | 248 | Generated for the directory containing the old filename |
f23fc716 | 249 | when a file is renamed. |
3f174f7d | 250 | .TP |
f23fc716 | 251 | .BR IN_MOVED_TO " (*)" |
107375cf | 252 | Generated for the directory containing the new filename |
f23fc716 | 253 | when a file is renamed. |
3f174f7d | 254 | .TP |
f23fc716 MK |
255 | .BR IN_OPEN " (*)" |
256 | File was opened. | |
64aa9bcb | 257 | .RE |
4d2b74dd | 258 | .PP |
c13182ef MK |
259 | When monitoring a directory, |
260 | the events marked with an asterisk (*) above can occur for | |
4d2b74dd MK |
261 | files in the directory, in which case the |
262 | .I name | |
263 | field in the returned | |
264 | .I inotify_event | |
265 | structure identifies the name of the file within the directory. | |
266 | .PP | |
267 | The | |
268 | .B IN_ALL_EVENTS | |
269 | macro is defined as a bit mask of all of the above events. | |
270 | This macro can be used as the | |
271 | .I mask | |
272 | argument when calling | |
63f6a20a | 273 | .BR inotify_add_watch (2). |
4d2b74dd | 274 | |
dede00fe | 275 | Two additional convenience macros are defined: |
64aa9bcb | 276 | .RS 4 |
dede00fe MK |
277 | .TP |
278 | .BR IN_MOVE | |
279 | Equates to | |
280 | .BR "IN_MOVED_FROM | IN_MOVED_TO" . | |
281 | .TP | |
282 | .BR IN_CLOSE | |
283 | Equates to | |
284 | .BR "IN_CLOSE_WRITE | IN_CLOSE_NOWRITE" . | |
64aa9bcb | 285 | .RE |
4d2b74dd | 286 | .PP |
c13182ef | 287 | The following further bits can be specified in |
4d2b74dd MK |
288 | .I mask |
289 | when calling | |
63f6a20a | 290 | .BR inotify_add_watch (2): |
64aa9bcb | 291 | .RS 4 |
c577b95c | 292 | .TP |
31daf529 | 293 | .BR IN_DONT_FOLLOW " (since Linux 2.6.15)" |
aeb9b6a6 MK |
294 | Don't dereference |
295 | .I pathname | |
296 | if it is a symbolic link. | |
dda869a4 | 297 | .TP |
0ff2cc88 | 298 | .BR IN_EXCL_UNLINK " (since Linux 2.6.36)" |
b3ad7609 MK |
299 | .\" commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6 |
300 | By default, when watching events on the children of a directory, | |
301 | events are generated for children even after they have been unlinked | |
302 | from the directory. | |
303 | This can result in large numbers of uninteresting events for | |
304 | some applications (e.g., if watching | |
305 | .IR /tmp , | |
306 | in which many applications create temporary files whose | |
307 | names are immediately unlinked). | |
308 | Specifying | |
309 | .B IN_EXCL_UNLINK | |
310 | changes the default behavior, | |
311 | so that events are not generated for children after | |
312 | they have been unlinked from the watched directory. | |
313 | .TP | |
dda869a4 MK |
314 | .B IN_MASK_ADD |
315 | Add (OR) events to watch mask for this pathname if | |
316 | it already exists (instead of replacing mask). | |
317 | .TP | |
318 | .B IN_ONESHOT | |
aeb9b6a6 MK |
319 | Monitor |
320 | .I pathname | |
321 | for one event, then remove from | |
dda869a4 MK |
322 | watch list. |
323 | .TP | |
31daf529 | 324 | .BR IN_ONLYDIR " (since Linux 2.6.15)" |
aeb9b6a6 MK |
325 | Only watch |
326 | .I pathname | |
327 | if it is a directory. | |
64aa9bcb | 328 | .RE |
4d2b74dd MK |
329 | .PP |
330 | The following bits may be set in the | |
331 | .I mask | |
332 | field returned by | |
63f6a20a | 333 | .BR read (2): |
64aa9bcb | 334 | .RS 4 |
c577b95c | 335 | .TP |
dda869a4 | 336 | .B IN_IGNORED |
aeb9b6a6 MK |
337 | Watch was removed explicitly |
338 | .RB ( inotify_rm_watch (2)) | |
9ee4a2b6 | 339 | or automatically (file was deleted, or filesystem was unmounted). |
7b5151b7 | 340 | See also BUGS. |
dda869a4 MK |
341 | .TP |
342 | .B IN_ISDIR | |
343 | Subject of this event is a directory. | |
344 | .TP | |
345 | .B IN_Q_OVERFLOW | |
aeb9b6a6 MK |
346 | Event queue overflowed |
347 | .RI ( wd | |
348 | is \-1 for this event). | |
dda869a4 MK |
349 | .TP |
350 | .B IN_UNMOUNT | |
9ee4a2b6 | 351 | Filesystem containing watched object was unmounted. |
b01c936e MK |
352 | In addition, an |
353 | .B IN_IGNORED | |
354 | event will subsequently be generated for the watch descriptor. | |
64aa9bcb | 355 | .RE |
415f63be MK |
356 | .SS Examples |
357 | Suppose an application is watching the directory | |
358 | .I dir | |
359 | and the file | |
360 | .IR dir/myfile | |
361 | for all events. | |
362 | The examples below show some events that will be generated | |
363 | for these two objects. | |
364 | .RS 4 | |
365 | .TP | |
366 | fd = open("dir/myfile", O_RDWR); | |
367 | Generates | |
368 | .B IN_OPEN | |
369 | events for both | |
370 | .I dir | |
371 | and | |
372 | .IR dir/myfile . | |
373 | .TP | |
374 | read(fd, buf, count); | |
375 | Generates | |
376 | .B IN_ACCESS | |
377 | events for both | |
378 | .I dir | |
379 | and | |
380 | .IR dir/myfile . | |
381 | .TP | |
382 | write(fd, buf, count); | |
383 | Generates | |
384 | .B IN_MODIFY | |
385 | events for both | |
386 | .I dir | |
387 | and | |
388 | .IR dir/myfile . | |
389 | .TP | |
390 | fchmod(fd, mode); | |
391 | Generates | |
392 | .B IN_ATTRIB | |
393 | events for both | |
394 | .I dir | |
395 | and | |
396 | .IR dir/myfile . | |
397 | .TP | |
398 | close(fd); | |
399 | Generates | |
400 | .B IN_CLOSE_WRITE | |
401 | events for both | |
402 | .I dir | |
403 | and | |
404 | .IR dir/myfile . | |
405 | .RE | |
406 | .PP | |
407 | Suppose an application is watching the directories | |
408 | .I dir1 | |
409 | and | |
410 | .IR dir , | |
411 | and the file | |
412 | .IR dir1/myfile . | |
413 | The following examples show some events that may be generated. | |
414 | .RS 4 | |
415 | .TP | |
416 | link("dir/myfile", "dir2/new"); | |
417 | Generates an | |
418 | .B IN_ATTRIB | |
419 | event for | |
420 | .IR myfile | |
421 | and an | |
422 | .B IN_CREATE | |
423 | event for | |
424 | .IR dir2 . | |
425 | .TP | |
426 | rename("dir1/myfile", "dir2/myfile"); | |
427 | Generates an | |
428 | .B IN_MOVED_FROM | |
429 | event for | |
430 | .IR dir1 , | |
431 | an | |
432 | .B IN_MOVED_TO | |
433 | event for | |
434 | .IR dir2 , | |
435 | and an | |
436 | .B IN_MOVE_SELF | |
437 | event for | |
438 | .IR myfile . | |
439 | The | |
440 | .B IN_MOVED_FROM | |
441 | and | |
442 | .B IN_MOVED_TO | |
443 | events will have the same | |
444 | .I cookie | |
445 | value. | |
446 | .RE | |
447 | .PP | |
448 | Suppose that | |
449 | .IR dir1/xx | |
450 | and | |
451 | .IR dir2/yy | |
452 | are (the only) links to the same file, and an application is watching | |
453 | .IR dir1 , | |
454 | .IR dir2 , | |
455 | .IR dir1/xx , | |
456 | and | |
457 | .IR dir2/yy . | |
458 | Executing the following calls in the order given below will generate | |
459 | the following events: | |
460 | .RS 4 | |
461 | .TP | |
462 | unlink("dir2/yy"); | |
463 | Generates | |
464 | .BR IN_ATTRIB | |
465 | event for | |
466 | .IR xx | |
467 | (because its link count changes) | |
468 | and an | |
469 | .B IN_DELETE | |
470 | event for | |
471 | .IR dir2 . | |
472 | .TP | |
473 | unlink("dir1/xx"); | |
474 | Generates | |
475 | .BR IN_ATTRIB , | |
476 | .BR IN_DELETE_SELF , | |
477 | and | |
478 | .BR IN_IGNORED | |
479 | events for | |
480 | .IR xx , | |
481 | and an | |
482 | .BR IN_DELETE | |
483 | for | |
484 | .IR dir1 . | |
485 | .RE | |
486 | .PP | |
487 | Suppose an application is watching the directory | |
488 | .IR dir | |
489 | and (the empty) directory | |
490 | .IR dir/subdir . | |
491 | The following examples show some events that may be generated. | |
492 | .RS 4 | |
493 | .TP | |
494 | mkdir("dir/new", mode); | |
495 | Generates an | |
496 | .B "IN_CREATE | IN_ISDIR" | |
497 | event for | |
498 | .IR dir . | |
499 | .TP | |
500 | rmdir("dir/sub"); | |
501 | Generates | |
502 | .B IN_DELETE_SELF | |
503 | and | |
504 | .B IN_IGNORED | |
505 | events for | |
506 | .IR subdir , | |
507 | and an | |
508 | .B "IN_DELETE | IN_ISDIR" | |
509 | event for | |
510 | .IR dir . | |
511 | .RE | |
4d2b74dd | 512 | .SS /proc interfaces |
c13182ef | 513 | The following interfaces can be used to limit the amount of |
4d2b74dd MK |
514 | kernel memory consumed by inotify: |
515 | .TP | |
0daa9e92 | 516 | .I /proc/sys/fs/inotify/max_queued_events |
4d2b74dd MK |
517 | The value in this file is used when an application calls |
518 | .BR inotify_init (2) | |
c13182ef | 519 | to set an upper limit on the number of events that can be |
4d2b74dd MK |
520 | queued to the corresponding inotify instance. |
521 | Events in excess of this limit are dropped, but an | |
522 | .B IN_Q_OVERFLOW | |
523 | event is always generated. | |
524 | .TP | |
0daa9e92 | 525 | .I /proc/sys/fs/inotify/max_user_instances |
c13182ef | 526 | This specifies an upper limit on the number of inotify instances |
4d2b74dd MK |
527 | that can be created per real user ID. |
528 | .TP | |
0daa9e92 | 529 | .I /proc/sys/fs/inotify/max_user_watches |
31546b46 VN |
530 | This specifies an upper limit on the number of watches |
531 | that can be created per real user ID. | |
47297adb | 532 | .SH VERSIONS |
2b2581ee MK |
533 | Inotify was merged into the 2.6.13 Linux kernel. |
534 | The required library interfaces were added to glibc in version 2.4. | |
535 | .RB ( IN_DONT_FOLLOW , | |
536 | .BR IN_MASK_ADD , | |
537 | and | |
538 | .B IN_ONLYDIR | |
64aa9bcb | 539 | were added in glibc version 2.5.) |
47297adb | 540 | .SH CONFORMING TO |
8382f16d | 541 | The inotify API is Linux-specific. |
47297adb | 542 | .SH NOTES |
4d2b74dd MK |
543 | Inotify file descriptors can be monitored using |
544 | .BR select (2), | |
545 | .BR poll (2), | |
c13182ef | 546 | and |
2315114c | 547 | .BR epoll (7). |
0000daa5 MK |
548 | When an event is available, the file descriptor indicates as readable. |
549 | ||
550 | Since Linux 2.6.25, | |
551 | signal-driven I/O notification is available for inotify file descriptors; | |
552 | see the discussion of | |
553 | .B F_SETFL | |
554 | (for setting the | |
555 | .B O_ASYNC | |
556 | flag), | |
557 | .BR F_SETOWN , | |
558 | and | |
559 | .B F_SETSIG | |
560 | in | |
561 | .BR fcntl (2). | |
562 | The | |
563 | .I siginfo_t | |
564 | structure (described in | |
565 | .BR sigaction (2)) | |
566 | that is passed to the signal handler has the following fields set: | |
567 | .IR si_fd | |
568 | is set to the inotify file descriptor number; | |
569 | .IR si_signo | |
570 | is set to the signal number; | |
571 | .IR si_code | |
572 | is set to | |
573 | .BR POLL_IN ; | |
574 | and | |
575 | .B POLLIN | |
576 | is set in | |
577 | .IR si_band . | |
4d2b74dd | 578 | |
c13182ef MK |
579 | If successive output inotify events produced on the |
580 | inotify file descriptor are identical (same | |
581 | .IR wd , | |
582 | .IR mask , | |
4d2b74dd MK |
583 | .IR cookie , |
584 | and | |
3f3698d8 | 585 | .IR name ), |
6f0ab035 MK |
586 | then they are coalesced into a single event if the |
587 | older event has not yet been read (but see BUGS). | |
8856aab8 MK |
588 | This reduces the amount of kernel memory required for the event queue, |
589 | but also means that an application can't use inotify to reliably count | |
590 | file events. | |
4d2b74dd | 591 | |
c13182ef MK |
592 | The events returned by reading from an inotify file descriptor |
593 | form an ordered queue. | |
594 | Thus, for example, it is guaranteed that when renaming from | |
595 | one directory to another, events will be produced in the | |
4d2b74dd MK |
596 | correct order on the inotify file descriptor. |
597 | ||
598 | The | |
599 | .B FIONREAD | |
63f6a20a | 600 | .BR ioctl (2) |
c13182ef | 601 | returns the number of bytes available to read from an |
4d2b74dd | 602 | inotify file descriptor. |
613836aa | 603 | .SS Limitations and caveats |
264276c6 MK |
604 | The inotify applications identifies events via watch descriptors. |
605 | It is the application's responsibility to cache a mapping | |
606 | (if one is needed) between watch descriptors and pathnames. | |
607 | Be aware that directory renamings may affect multiple cached pathnames. | |
608 | ||
4d2b74dd MK |
609 | Inotify monitoring of directories is not recursive: |
610 | to monitor subdirectories under a directory, | |
611 | additional watches must be created. | |
613836aa MK |
612 | This can take a significant amount time for large directory trees. |
613 | ||
a79d28b2 MK |
614 | If monitoring an entire directory subtree, |
615 | and a new subdirectory is created in that tree or an existing directory | |
616 | is renamed into that tree, | |
617 | be aware that by the time you create a watch for the new subdirectory, | |
618 | new files (and subdirectories) may already exist inside the subdirectory. | |
619 | Therefore, you may want to scan the contents of the subdirectory | |
620 | immediately after adding the watch (and, if desired, | |
621 | recursively add watches for any subdirectories that it contains). | |
622 | ||
4d2ddb4e MK |
623 | The inotify API provides no information about the user or process that |
624 | triggered the inotify event. | |
99e603bd MK |
625 | In particular, there is no easy |
626 | way for a process that is monitoring events via inotify | |
627 | to distinguish events that it triggers | |
628 | itself from those that are triggered by other processes. | |
4d2ddb4e | 629 | |
613836aa MK |
630 | Note that the event queue can overflow. |
631 | In this case, events are lost. | |
09fa72fa | 632 | Robust applications should handle the possibility of |
613836aa | 633 | lost events gracefully. |
94d52c15 MK |
634 | For example, it may be necessary to rebuild part or all of |
635 | the application cache. | |
636 | (One simple, but possibly expensive, | |
637 | approach is to close the inotify file descriptor, empty the cache, | |
85e179c5 | 638 | create a new inotify file descriptor, |
94d52c15 MK |
639 | and then re-create watches and cache entries |
640 | for the objects to be monitored.) | |
613836aa MK |
641 | |
642 | The inotify API identifies affected files by filename. | |
643 | However, by the time an application processes an inotify event, | |
644 | the filename may already have been deleted or renamed. | |
85e179c5 MK |
645 | .SS Dealing with rename() events |
646 | The | |
647 | .B IN_MOVED_FROM | |
648 | and | |
649 | .B IN_MOVED_TO | |
650 | events that are generated by | |
651 | .BR rename (2) | |
652 | are usually available as consecutive events when reading | |
653 | from the inotify file descriptor. | |
654 | However, this is not guaranteed. | |
655 | If multiple processes are triggering events for monitored objects, | |
656 | then (on rare occasions) an arbitrary number of | |
657 | other events may appear between the | |
658 | .B IN_MOVED_FROM | |
659 | and | |
660 | .B IN_MOVED_TO | |
661 | events. | |
662 | ||
663 | Matching up the | |
664 | .B IN_MOVED_FROM | |
665 | and | |
666 | .B IN_MOVED_TO | |
667 | event pair generated by | |
668 | .BR rename (2) | |
669 | is thus inherently racy. | |
670 | (Don't forget that if an object is renamed outside of a monitored directory, | |
671 | there may not even be an | |
672 | .BR IN_MOVED_TO | |
673 | event.) | |
674 | Heuristic approaches (e.g., assume the events are always consecutive) | |
675 | can be used to ensure a match in most cases, | |
676 | but will inevitably miss some cases, | |
677 | causing the application to perceive the | |
678 | .B IN_MOVED_FROM | |
679 | and | |
680 | .B IN_MOVED_TO | |
681 | events as being unrelated. | |
682 | If watch descriptors are destroyed and re-created as a result, | |
683 | then those watch descriptors will be inconsistent with | |
684 | the watch descriptors in any pending events. | |
685 | (Rebuilding the cache and re-creating the inotify file descriptor may | |
686 | be useful to deal with this scenario.) | |
687 | ||
688 | Applications should also allow for the possibility that the | |
689 | .B IN_MOVED_FROM | |
690 | event was the last event that could fit in the buffer | |
691 | returned by the current call to | |
692 | .BR read (2), | |
693 | and the accompanying | |
694 | .B IN_MOVED_TO | |
695 | event might be fetched only on the next | |
696 | .BR read (2). | |
47297adb | 697 | .SH BUGS |
a15ead5e MK |
698 | .\" FIXME kernel commit 611da04f7a31b2208e838be55a42c7a1310ae321 |
699 | .\" implies that unmount events were buggy 2.6.11 to 2.6.36 | |
700 | .\" | |
ed7b0235 MK |
701 | In kernels before 2.6.16, the |
702 | .B IN_ONESHOT | |
c13182ef | 703 | .I mask |
ed7b0235 | 704 | flag does not work. |
6f0ab035 | 705 | |
7b5151b7 MK |
706 | As originally designed and implemented, the |
707 | .B IN_ONESHOT | |
708 | flag did not cause an | |
709 | .B IN_IGNORED | |
710 | event to be generated when the watch was dropped after one event. | |
711 | However, as an unintended effect of other changes, | |
712 | since Linux 2.6.36, an | |
713 | .B IN_IGNORED | |
714 | event is generated in this case. | |
715 | ||
6f0ab035 | 716 | Before kernel 2.6.25, |
22129aa9 | 717 | .\" commit 1c17d18e3775485bf1e0ce79575eb637a94494a2 |
9ed6b517 | 718 | the kernel code that was intended to coalesce successive identical events |
6f0ab035 MK |
719 | (i.e., the two most recent events could potentially be coalesced |
720 | if the older had not yet been read) | |
721 | instead checked if the most recent event could be coalesced with the | |
722 | .I oldest | |
723 | unread event. | |
47297adb | 724 | .SH SEE ALSO |
f0afb16a MK |
725 | .BR inotifywait (1), |
726 | .BR inotifywatch (1), | |
4d2b74dd MK |
727 | .BR inotify_add_watch (2), |
728 | .BR inotify_init (2), | |
43bb5faf | 729 | .BR inotify_init1 (2), |
4d2b74dd MK |
730 | .BR inotify_rm_watch (2), |
731 | .BR read (2), | |
173fe7e7 DP |
732 | .BR stat (2) |
733 | ||
734 | .IR Documentation/filesystems/inotify.txt | |
735 | in the Linux kernel source tree |