Debian Codegraph @

upstream/debian-unstable/man7/inotify.7

raw
1 .\" Copyright 2006-2014, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH inotify 7 2026-02-14 "Linux man-pages 6.18"
7 .SH NAME
8 inotify \- monitoring filesystem events
9 .SH DESCRIPTION
10 The
11 .I inotify
12 API provides a mechanism for monitoring filesystem events.
13 Inotify can be used to monitor individual files,
14 or to monitor directories.
15 When a directory is monitored, inotify will return events
16 for the directory itself, and for files inside the directory.
17 .P
18 The following system calls are used with this API:
19 .IP \[bu] 3
20 .BR inotify_init (2)
21 creates an inotify instance and returns a file descriptor
22 referring to the inotify instance.
23 The more recent
24 .BR inotify_init1 (2)
25 is like
26 .BR inotify_init (2),
27 but has a
28 .I flags
29 argument that provides access to some extra functionality.
30 .IP \[bu]
31 .BR inotify_add_watch (2)
32 manipulates the "watch list" associated with an inotify instance.
33 Each item ("watch") in the watch list specifies the pathname of
34 a file or directory,
35 along with some set of events that the kernel should monitor for the
36 file referred to by that pathname.
37 .BR inotify_add_watch (2)
38 either creates a new watch item, or modifies an existing watch.
39 Each watch has a unique "watch descriptor", an integer
40 returned by
41 .BR inotify_add_watch (2)
42 when the watch is created.
43 .IP \[bu]
44 When events occur for monitored files and directories,
45 those events are made available to the application as structured data that
46 can be read from the inotify file descriptor using
47 .BR read (2)
48 (see below).
49 .IP \[bu]
50 .BR inotify_rm_watch (2)
51 removes an item from an inotify watch list.
52 .IP \[bu]
53 When all file descriptors referring to an inotify
54 instance have been closed (using
55 .BR close (2)),
56 the underlying object and its resources are
57 freed for reuse by the kernel;
58 all associated watches are automatically freed.
59 .P
60 With careful programming,
61 an application can use inotify to efficiently monitor and cache
62 the state of a set of filesystem objects.
63 However, robust applications should allow for the fact that bugs
64 in the monitoring logic or races of the kind described below
65 may leave the cache inconsistent with the filesystem state.
66 It is probably wise to do some consistency checking,
67 and rebuild the cache when inconsistencies are detected.
68 .SS Reading events from an inotify file descriptor
69 To determine what events have occurred, an application
70 .BR read (2)s
71 from the inotify file descriptor.
72 If no events have so far occurred, then,
73 assuming a blocking file descriptor,
74 .BR read (2)
75 will block until at least one event occurs
76 (unless interrupted by a signal,
77 in which case the call fails with the error
78 .BR EINTR ;
79 see
80 .BR signal (7)).
81 .P
82 Each successful
83 .BR read (2)
84 returns a buffer containing one or more of the following structures:
85 .P
86 .in +4n
87 .EX
88 struct inotify_event {
89 int wd; /* Watch descriptor */
90 .\" FIXME . The type of the 'wd' field should probably be "int32_t".
91 .\" I submitted a patch to fix this. See the LKML thread
92 .\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008
93 .\" glibc bug filed: https://www.sourceware.org/bugzilla/show_bug.cgi?id=7040
94 uint32_t mask; /* Mask describing event */
95 uint32_t cookie; /* Unique cookie associating related
96 events (for rename(2)) */
97 uint32_t len; /* Size of \f[I]name\f[] field */
98 char name[]; /* Optional null\-terminated name */
99 };
100 .EE
101 .in
102 .P
103 .I wd
104 identifies the watch for which this event occurs.
105 It is one of the watch descriptors returned by a previous call to
106 .BR inotify_add_watch (2).
107 .P
108 .I mask
109 contains bits that describe the event that occurred (see below).
110 .P
111 .I cookie
112 is a unique integer that connects related events.
113 Currently, this is used only for rename events, and
114 allows the resulting pair of
115 .B IN_MOVED_FROM
116 and
117 .B IN_MOVED_TO
118 events to be connected by the application.
119 For all other event types,
120 .I cookie
121 is set to 0.
122 .P
123 The
124 .I name
125 field is present only when an event is returned
126 for a file inside a watched directory;
127 it identifies the filename within the watched directory.
128 This filename is null-terminated,
129 and may include further null bytes (\[aq]\[rs]0\[aq])
130 to align subsequent reads to a suitable address boundary.
131 .P
132 The
133 .I len
134 field counts all of the bytes in
135 .IR name ,
136 including the null bytes;
137 the size of each
138 .I inotify_event
139 structure is thus
140 .IR "sizeof(struct inotify_event)+size" .
141 .P
142 The behavior when the buffer given to
143 .BR read (2)
144 is too small to return information about the next event depends
145 on the kernel version: before Linux 2.6.21,
146 .BR read (2)
147 returns 0; since Linux 2.6.21,
148 .BR read (2)
149 fails with the error
150 .BR EINVAL .
151 Specifying a buffer of size
152 .P
153 .in +4n
154 .EX
155 sizeof(struct inotify_event) + NAME_MAX + 1
156 .EE
157 .in
158 .P
159 will be sufficient to read at least one event.
160 .SS inotify events
161 The
162 .BR inotify_add_watch (2)
163 .I mask
164 argument and the
165 .I mask
166 field of the
167 .I inotify_event
168 structure returned when
169 .BR read (2)ing
170 an inotify file descriptor are both bit masks identifying
171 inotify events.
172 The following bits can be specified in
173 .I mask
174 when calling
175 .BR inotify_add_watch (2)
176 and may be returned in the
177 .I mask
178 field returned by
179 .BR read (2):
180 .RS 4
181 .TP
182 .BR IN_ACCESS " (+)"
183 File was accessed (e.g.,
184 .BR read (2),
185 .BR execve (2)).
186 .TP
187 .BR IN_ATTRIB " (*)"
188 Metadata changed\[em]for example, permissions (e.g.,
189 .BR chmod (2)),
190 timestamps (e.g.,
191 .BR utimensat (2)),
192 extended attributes
193 .RB ( setxattr (2)),
194 link count
195 (since Linux 2.6.25;
196 e.g.,
197 .\" FIXME .
198 .\" Events do not occur for link count changes on a file inside a monitored
199 .\" directory. This differs from other metadata changes for files inside
200 .\" a monitored directory.
201 for the target of
202 .BR link (2)
203 and for
204 .BR unlink (2)),
205 and user/group ID (e.g.,
206 .BR chown (2)).
207 .TP
208 .BR IN_CLOSE_WRITE " (+)"
209 File opened for writing was closed.
210 .TP
211 .BR IN_CLOSE_NOWRITE " (*)"
212 File or directory not opened for writing was closed.
213 .TP
214 .BR IN_CREATE " (+)"
215 File/directory created in watched directory (e.g.,
216 .BR open (2)
217 .BR O_CREAT ,
218 .BR mkdir (2),
219 .BR link (2),
220 .BR symlink (2),
221 .BR bind (2)
222 on a UNIX domain socket).
223 .TP
224 .BR IN_DELETE " (+)"
225 File/directory deleted from watched directory.
226 .TP
227 .B IN_DELETE_SELF
228 Watched file/directory was itself deleted.
229 (This event also occurs if an object is moved to another filesystem,
230 since
231 .BR mv (1)
232 in effect copies the file to the other filesystem and
233 then deletes it from the original filesystem.)
234 In addition, an
235 .B IN_IGNORED
236 event will subsequently be generated for the watch descriptor.
237 .TP
238 .BR IN_MODIFY " (+)"
239 File was modified (e.g.,
240 .BR write (2),
241 .BR truncate (2)).
242 .TP
243 .B IN_MOVE_SELF
244 Watched file/directory was itself moved.
245 .TP
246 .BR IN_MOVED_FROM " (+)"
247 Generated for the directory containing the old filename
248 when a file is renamed.
249 .TP
250 .BR IN_MOVED_TO " (+)"
251 Generated for the directory containing the new filename
252 when a file is renamed.
253 .TP
254 .BR IN_OPEN " (*)"
255 File or directory was opened.
256 .RE
257 .P
258 Inotify monitoring is inode-based: when monitoring a file
259 (but not when monitoring the directory containing a file),
260 an event can be generated for activity on any link to the file
261 (in the same or a different directory).
262 .P
263 When monitoring a directory:
264 .IP \[bu] 3
265 the events marked above with an asterisk (*) can occur both
266 for the directory itself and for objects inside the directory;
267 and
268 .IP \[bu]
269 the events marked with a plus sign (+) occur only for objects
270 inside the directory (not for the directory itself).
271 .P
272 .IR Note :
273 when monitoring a directory,
274 events are not generated for the files inside the directory
275 when the events are performed via a pathname (i.e., a link)
276 that lies outside the monitored directory.
277 .P
278 When events are generated for objects inside a watched directory, the
279 .I name
280 field in the returned
281 .I inotify_event
282 structure identifies the name of the file within the directory.
283 .P
284 The
285 .B IN_ALL_EVENTS
286 macro is defined as a bit mask of all of the above events.
287 This macro can be used as the
288 .I mask
289 argument when calling
290 .BR inotify_add_watch (2).
291 .P
292 Two additional convenience macros are defined:
293 .RS 4
294 .TP
295 .B IN_MOVE
296 Equates to
297 .BR "IN_MOVED_FROM | IN_MOVED_TO" .
298 .TP
299 .B IN_CLOSE
300 Equates to
301 .BR "IN_CLOSE_WRITE | IN_CLOSE_NOWRITE" .
302 .RE
303 .P
304 The following further bits can be specified in
305 .I mask
306 when calling
307 .BR inotify_add_watch (2):
308 .RS 4
309 .TP
310 .BR IN_DONT_FOLLOW " (since Linux 2.6.15)"
311 Don't dereference
312 .I pathname
313 if it is a symbolic link.
314 .TP
315 .BR IN_EXCL_UNLINK " (since Linux 2.6.36)"
316 .\" commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6
317 By default, when watching events on the children of a directory,
318 events are generated for children even after they have been unlinked
319 from the directory.
320 This can result in large numbers of uninteresting events for
321 some applications (e.g., if watching
322 .IR /tmp ,
323 in which many applications create temporary files whose
324 names are immediately unlinked).
325 Specifying
326 .B IN_EXCL_UNLINK
327 changes the default behavior,
328 so that events are not generated for children after
329 they have been unlinked from the watched directory.
330 .TP
331 .B IN_MASK_ADD
332 If a watch instance already exists for the filesystem object corresponding to
333 .IR pathname ,
334 add (OR) the events in
335 .I mask
336 to the watch mask (instead of replacing the mask);
337 the error
338 .B EINVAL
339 results if
340 .B IN_MASK_CREATE
341 is also specified.
342 .TP
343 .B IN_ONESHOT
344 Monitor the filesystem object corresponding to
345 .I pathname
346 for one event, then remove from
347 watch list.
348 .TP
349 .BR IN_ONLYDIR " (since Linux 2.6.15)"
350 Watch
351 .I pathname
352 only if it is a directory;
353 the error
354 .B ENOTDIR
355 results if
356 .I pathname
357 is not a directory.
358 Using this flag provides an application with a race-free way of
359 ensuring that the monitored object is a directory.
360 .TP
361 .BR IN_MASK_CREATE " (since Linux 4.18)"
362 Watch
363 .I pathname
364 only if it does not already have a watch associated with it;
365 the error
366 .B EEXIST
367 results if
368 .I pathname
369 is already being watched.
370 .IP
371 Using this flag provides an application with a way of ensuring
372 that new watches do not modify existing ones.
373 This is useful because multiple paths may refer to the same inode,
374 and multiple calls to
375 .BR inotify_add_watch (2)
376 without this flag may clobber existing watch masks.
377 .RE
378 .P
379 The following bits may be set in the
380 .I mask
381 field returned by
382 .BR read (2):
383 .RS 4
384 .TP
385 .B IN_IGNORED
386 Watch was removed explicitly
387 .RB ( inotify_rm_watch (2))
388 or automatically (file was deleted, or filesystem was unmounted).
389 See also BUGS.
390 .TP
391 .B IN_ISDIR
392 Subject of this event is a directory.
393 .TP
394 .B IN_Q_OVERFLOW
395 Event queue overflowed
396 .RI ( wd
397 is \-1 for this event).
398 .TP
399 .B IN_UNMOUNT
400 Filesystem containing watched object was unmounted.
401 In addition, an
402 .B IN_IGNORED
403 event will subsequently be generated for the watch descriptor.
404 .RE
405 .SS Examples
406 Suppose an application is watching the directory
407 .I dir
408 and the file
409 .I dir/myfile
410 for all events.
411 The examples below show some events that will be generated
412 for these two objects.
413 .RS 4
414 .TP
415 fd = open("dir/myfile", O_RDWR);
416 Generates
417 .B IN_OPEN
418 events for both
419 .I dir
420 and
421 .IR dir/myfile .
422 .TP
423 read(fd, buf, count);
424 Generates
425 .B IN_ACCESS
426 events for both
427 .I dir
428 and
429 .IR dir/myfile .
430 .TP
431 write(fd, buf, count);
432 Generates
433 .B IN_MODIFY
434 events for both
435 .I dir
436 and
437 .IR dir/myfile .
438 .TP
439 fchmod(fd, mode);
440 Generates
441 .B IN_ATTRIB
442 events for both
443 .I dir
444 and
445 .IR dir/myfile .
446 .TP
447 close(fd);
448 Generates
449 .B IN_CLOSE_WRITE
450 events for both
451 .I dir
452 and
453 .IR dir/myfile .
454 .RE
455 .P
456 Suppose an application is watching the directories
457 .I dir1
458 and
459 .IR dir2 ,
460 and the file
461 .IR dir1/myfile .
462 The following examples show some events that may be generated.
463 .RS 4
464 .TP
465 link("dir1/myfile", "dir2/new");
466 Generates an
467 .B IN_ATTRIB
468 event for
469 .I myfile
470 and an
471 .B IN_CREATE
472 event for
473 .IR dir2 .
474 .TP
475 rename("dir1/myfile", "dir2/myfile");
476 Generates an
477 .B IN_MOVED_FROM
478 event for
479 .IR dir1 ,
480 an
481 .B IN_MOVED_TO
482 event for
483 .IR dir2 ,
484 and an
485 .B IN_MOVE_SELF
486 event for
487 .IR myfile .
488 The
489 .B IN_MOVED_FROM
490 and
491 .B IN_MOVED_TO
492 events will have the same
493 .I cookie
494 value.
495 .RE
496 .P
497 Suppose that
498 .I dir1/xx
499 and
500 .I dir2/yy
501 are (the only) links to the same file, and an application is watching
502 .IR dir1 ,
503 .IR dir2 ,
504 .IR dir1/xx ,
505 and
506 .IR dir2/yy .
507 Executing the following calls in the order given below will generate
508 the following events:
509 .RS 4
510 .TP
511 unlink("dir2/yy");
512 Generates an
513 .B IN_ATTRIB
514 event for
515 .I xx
516 (because its link count changes)
517 and an
518 .B IN_DELETE
519 event for
520 .IR dir2 .
521 .TP
522 unlink("dir1/xx");
523 Generates
524 .BR IN_ATTRIB ,
525 .BR IN_DELETE_SELF ,
526 and
527 .B IN_IGNORED
528 events for
529 .IR xx ,
530 and an
531 .B IN_DELETE
532 event for
533 .IR dir1 .
534 .RE
535 .P
536 Suppose an application is watching the directory
537 .I dir
538 and (the empty) directory
539 .IR dir/subdir .
540 The following examples show some events that may be generated.
541 .RS 4
542 .TP
543 mkdir("dir/new", mode);
544 Generates an
545 .B "IN_CREATE | IN_ISDIR"
546 event for
547 .IR dir .
548 .TP
549 rmdir("dir/subdir");
550 Generates
551 .B IN_DELETE_SELF
552 and
553 .B IN_IGNORED
554 events for
555 .IR subdir ,
556 and an
557 .B "IN_DELETE | IN_ISDIR"
558 event for
559 .IR dir .
560 .RE
561 .SS /proc interfaces
562 The following interfaces can be used to limit the amount of
563 kernel memory consumed by inotify:
564 .TP
565 .I /proc/sys/fs/inotify/max_queued_events
566 The value in this file is used when an application calls
567 .BR inotify_init (2)
568 to set an upper limit on the number of events that can be
569 queued to the corresponding inotify instance.
570 Events in excess of this limit are dropped, but an
571 .B IN_Q_OVERFLOW
572 event is always generated.
573 .TP
574 .I /proc/sys/fs/inotify/max_user_instances
575 This specifies an upper limit on the number of inotify instances
576 that can be created per real user ID.
577 .TP
578 .I /proc/sys/fs/inotify/max_user_watches
579 This specifies an upper limit on the number of watches
580 that can be created per real user ID.
581 .SH STANDARDS
582 Linux.
583 .SH HISTORY
584 Inotify was merged into Linux 2.6.13.
585 The required library interfaces were added in glibc 2.4.
586 .RB ( IN_DONT_FOLLOW ,
587 .BR IN_MASK_ADD ,
588 and
589 .B IN_ONLYDIR
590 were added in glibc 2.5.)
591 .SH NOTES
592 Inotify file descriptors can be monitored using
593 .BR select (2),
594 .BR poll (2),
595 and
596 .BR epoll (7).
597 When an event is available, the file descriptor indicates as readable.
598 .P
599 Since Linux 2.6.25,
600 signal-driven I/O notification is available for inotify file descriptors;
601 see the discussion of
602 .B F_SETFL
603 (for setting the
604 .B O_ASYNC
605 flag),
606 .BR F_SETOWN ,
607 and
608 .B F_SETSIG
609 in
610 .BR fcntl (2).
611 The
612 .I siginfo_t
613 structure (described in
614 .BR sigaction (2))
615 that is passed to the signal handler has the following fields set:
616 .I si_fd
617 is set to the inotify file descriptor number;
618 .I si_signo
619 is set to the signal number;
620 .I si_code
621 is set to
622 .BR POLL_IN ;
623 and
624 .B POLLIN
625 is set in
626 .IR si_band .
627 .P
628 If successive output inotify events produced on the
629 inotify file descriptor are identical (same
630 .IR wd ,
631 .IR mask ,
632 .IR cookie ,
633 and
634 .IR name ),
635 then they are coalesced into a single event if the
636 older event has not yet been read (but see BUGS).
637 This reduces the amount of kernel memory required for the event queue,
638 but also means that an application can't use inotify to reliably count
639 file events.
640 .P
641 The events returned by reading from an inotify file descriptor
642 form an ordered queue.
643 Thus, for example, it is guaranteed that when renaming from
644 one directory to another, events will be produced in the
645 correct order on the inotify file descriptor.
646 .P
647 The set of watch descriptors that is being monitored via
648 an inotify file descriptor can be viewed via the entry for
649 the inotify file descriptor in the process's
650 .IR /proc/ pid /fdinfo
651 directory.
652 See
653 .BR proc (5)
654 for further details.
655 The
656 .B FIONREAD
657 .BR ioctl (2)
658 returns the number of bytes available to read from an
659 inotify file descriptor.
660 .SS Limitations and caveats
661 The inotify API provides no information about the user or process that
662 triggered the inotify event.
663 In particular, there is no easy
664 way for a process that is monitoring events via inotify
665 to distinguish events that it triggers
666 itself from those that are triggered by other processes.
667 .P
668 Inotify reports only events that a user-space program triggers through
669 the filesystem API.
670 As a result, it does not catch remote events that occur
671 on network filesystems.
672 (Applications must fall back to polling the filesystem
673 to catch such events.)
674 Furthermore, various pseudo-filesystems such as
675 .IR /proc ,
676 .IR /sys ,
677 and
678 .I /dev/pts
679 are not monitorable with inotify.
680 .P
681 The inotify API does not report file accesses and modifications that
682 may occur because of
683 .BR mmap (2),
684 .BR msync (2),
685 and
686 .BR munmap (2).
687 .P
688 The inotify API identifies affected files by filename.
689 However, by the time an application processes an inotify event,
690 the filename may already have been deleted or renamed.
691 .P
692 The inotify API identifies events via watch descriptors.
693 It is the application's responsibility to cache a mapping
694 (if one is needed) between watch descriptors and pathnames.
695 Be aware that directory renamings may affect multiple cached pathnames.
696 .P
697 Inotify monitoring of directories is not recursive:
698 to monitor subdirectories under a directory,
699 additional watches must be created.
700 This can take a significant amount time for large directory trees.
701 .P
702 If monitoring an entire directory subtree,
703 and a new subdirectory is created in that tree or an existing directory
704 is renamed into that tree,
705 be aware that by the time you create a watch for the new subdirectory,
706 new files (and subdirectories) may already exist inside the subdirectory.
707 Therefore, you may want to scan the contents of the subdirectory
708 immediately after adding the watch (and, if desired,
709 recursively add watches for any subdirectories that it contains).
710 .P
711 Note that the event queue can overflow.
712 In this case, events are lost.
713 Robust applications should handle the possibility of
714 lost events gracefully.
715 For example, it may be necessary to rebuild part or all of
716 the application cache.
717 (One simple, but possibly expensive,
718 approach is to close the inotify file descriptor, empty the cache,
719 create a new inotify file descriptor,
720 and then re-create watches and cache entries
721 for the objects to be monitored.)
722 .P
723 If a filesystem is mounted on top of a monitored directory,
724 no event is generated, and no events are generated
725 for objects immediately under the new mount point.
726 If the filesystem is subsequently unmounted,
727 events will subsequently be generated for the directory and
728 the objects it contains.
729 .\"
730 .SS Dealing with rename() events
731 As noted above, the
732 .B IN_MOVED_FROM
733 and
734 .B IN_MOVED_TO
735 event pair that is generated by
736 .BR rename (2)
737 can be matched up via their shared cookie value.
738 However, the task of matching has some challenges.
739 .P
740 These two events are usually consecutive in the event stream available
741 when reading from the inotify file descriptor.
742 However, this is not guaranteed.
743 If multiple processes are triggering events for monitored objects,
744 then (on rare occasions) an arbitrary number of
745 other events may appear between the
746 .B IN_MOVED_FROM
747 and
748 .B IN_MOVED_TO
749 events.
750 Furthermore, it is not guaranteed that the event pair is atomically
751 inserted into the queue: there may be a brief interval where the
752 .B IN_MOVED_FROM
753 has appeared, but the
754 .B IN_MOVED_TO
755 has not.
756 .P
757 Matching up the
758 .B IN_MOVED_FROM
759 and
760 .B IN_MOVED_TO
761 event pair generated by
762 .BR rename (2)
763 is thus inherently racy.
764 (Don't forget that if an object is renamed outside of a monitored directory,
765 there may not even be an
766 .B IN_MOVED_TO
767 event.)
768 Heuristic approaches (e.g., assume the events are always consecutive)
769 can be used to ensure a match in most cases,
770 but will inevitably miss some cases,
771 causing the application to perceive the
772 .B IN_MOVED_FROM
773 and
774 .B IN_MOVED_TO
775 events as being unrelated.
776 If watch descriptors are destroyed and re-created as a result,
777 then those watch descriptors will be inconsistent with
778 the watch descriptors in any pending events.
779 (Re-creating the inotify file descriptor and rebuilding the cache may
780 be useful to deal with this scenario.)
781 .P
782 Applications should also allow for the possibility that the
783 .B IN_MOVED_FROM
784 event was the last event that could fit in the buffer
785 returned by the current call to
786 .BR read (2),
787 and the accompanying
788 .B IN_MOVED_TO
789 event might be fetched only on the next
790 .BR read (2),
791 which should be done with a (small) timeout to allow for the fact that
792 insertion of the
793 .BR IN_MOVED_FROM + IN_MOVED_TO
794 event pair is not atomic,
795 and also the possibility that there may not be any
796 .B IN_MOVED_TO
797 event.
798 .SH BUGS
799 Before Linux 3.19,
800 .BR fallocate (2)
801 did not create any inotify events.
802 Since Linux 3.19,
803 .\" commit 820c12d5d6c0890bc93dd63893924a13041fdc35
804 calls to
805 .BR fallocate (2)
806 generate
807 .B IN_MODIFY
808 events.
809 .P
810 .\" FIXME . kernel commit 611da04f7a31b2208e838be55a42c7a1310ae321
811 .\" implies that unmount events were buggy since Linux 2.6.11 to Linux 2.6.36
812 .\"
813 Before Linux 2.6.16, the
814 .B IN_ONESHOT
815 .I mask
816 flag does not work.
817 .P
818 As originally designed and implemented, the
819 .B IN_ONESHOT
820 flag did not cause an
821 .B IN_IGNORED
822 event to be generated when the watch was dropped after one event.
823 However, as an unintended effect of other changes,
824 since Linux 2.6.36, an
825 .B IN_IGNORED
826 event is generated in this case.
827 .P
828 Before Linux 2.6.25,
829 .\" commit 1c17d18e3775485bf1e0ce79575eb637a94494a2
830 the kernel code that was intended to coalesce successive identical events
831 (i.e., the two most recent events could potentially be coalesced
832 if the older had not yet been read)
833 instead checked if the most recent event could be coalesced with the
834 .I oldest
835 unread event.
836 .P
837 When a watch descriptor is removed by calling
838 .BR inotify_rm_watch (2)
839 (or because a watch file is deleted or the filesystem
840 that contains it is unmounted),
841 any pending unread events for that watch descriptor remain available to read.
842 As watch descriptors are subsequently allocated with
843 .BR inotify_add_watch (2),
844 the kernel cycles through the range of possible watch descriptors (1 to
845 .BR INT_MAX )
846 incrementally.
847 When allocating a free watch descriptor, no check is made to see whether that
848 watch descriptor number has any pending unread events in the inotify queue.
849 Thus, it can happen that a watch descriptor is reallocated even
850 when pending unread events exist for a previous incarnation of
851 that watch descriptor number, with the result that the application
852 might then read those events and interpret them as belonging to
853 the file associated with the newly recycled watch descriptor.
854 In practice, the likelihood of hitting this bug may be extremely low,
855 since it requires that an application cycle through
856 .B INT_MAX
857 watch descriptors,
858 release a watch descriptor while leaving unread events for that
859 watch descriptor in the queue,
860 and then recycle that watch descriptor.
861 For this reason, and because there have been no reports
862 of the bug occurring in real-world applications,
863 as of Linux 3.15,
864 .\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=77111
865 no kernel changes have yet been made to eliminate this possible bug.
866 .SH EXAMPLES
867 The following program demonstrates the usage of the inotify API.
868 It marks the directories passed as a command-line arguments
869 and waits for events of type
870 .BR IN_OPEN ,
871 .BR IN_CLOSE_NOWRITE ,
872 and
873 .BR IN_CLOSE_WRITE .
874 .P
875 The following output was recorded while editing the file
876 .I /home/user/temp/foo
877 and listing directory
878 .IR /tmp .
879 Before the file and the directory were opened,
880 .B IN_OPEN
881 events occurred.
882 After the file was closed, an
883 .B IN_CLOSE_WRITE
884 event occurred.
885 After the directory was closed, an
886 .B IN_CLOSE_NOWRITE
887 event occurred.
888 Execution of the program ended when the user pressed the ENTER key.
889 .SS Example output
890 .in +4n
891 .EX
892 .RB $ " ./a.out /tmp /home/user/temp" ;
893 Press enter key to terminate.
894 Listening for events.
895 IN_OPEN: /home/user/temp/foo [file]
896 IN_CLOSE_WRITE: /home/user/temp/foo [file]
897 IN_OPEN: /tmp/ [directory]
898 IN_CLOSE_NOWRITE: /tmp/ [directory]
899 \&
900 Listening for events stopped.
901 .EE
902 .in
903 .SS Program source
904 \&
905 .EX
906 #include <errno.h>
907 #include <poll.h>
908 #include <stdio.h>
909 #include <stdlib.h>
910 #include <sys/inotify.h>
911 #include <unistd.h>
912 #include <string.h>
913 \&
914 /* Read all available inotify events from the file descriptor \[aq]fd\[aq].
915 wd is the table of watch descriptors for the directories in argv.
916 argc is the size of wd and argv.
917 argv is the list of watched directories.
918 Entry 0 of wd and argv is unused. */
919 \&
920 static void
921 handle_events(int fd, int *wd, int argc, char* argv[])
922 {
923 /* Some systems cannot read integer variables if they are not
924 properly aligned. On other systems, incorrect alignment may
925 decrease performance. Hence, the buffer used for reading from
926 the inotify file descriptor should have the same alignment as
927 struct inotify_event. */
928 \&
929 char buf[4096]
930 __attribute__ ((aligned(__alignof__(struct inotify_event))));
931 const struct inotify_event *event;
932 ssize_t size;
933 \&
934 /* Loop while events can be read from inotify file descriptor. */
935 \&
936 for (;;) {
937 \&
938 /* Read some events. */
939 \&
940 size = read(fd, buf, sizeof(buf));
941 if (size == \-1 && errno != EAGAIN) {
942 perror("read");
943 exit(EXIT_FAILURE);
944 }
945 \&
946 /* If the nonblocking read() found no events to read, then
947 it returns \-1 with errno set to EAGAIN. In that case,
948 we exit the loop. */
949 \&
950 if (size <= 0)
951 break;
952 \&
953 /* Loop over all events in the buffer. */
954 \&
955 for (char *ptr = buf; ptr < buf + size;
956 ptr += sizeof(struct inotify_event) + event\->len) {
957 \&
958 event = (const struct inotify_event *) ptr;
959 \&
960 /* Print event type. */
961 \&
962 if (event\->mask & IN_OPEN)
963 printf("IN_OPEN: ");
964 if (event\->mask & IN_CLOSE_NOWRITE)
965 printf("IN_CLOSE_NOWRITE: ");
966 if (event\->mask & IN_CLOSE_WRITE)
967 printf("IN_CLOSE_WRITE: ");
968 \&
969 /* Print the name of the watched directory. */
970 \&
971 for (size_t i = 1; i < argc; ++i) {
972 if (wd[i] == event\->wd) {
973 printf("%s/", argv[i]);
974 break;
975 }
976 }
977 \&
978 /* Print the name of the file. */
979 \&
980 if (event\->len)
981 printf("%s", event\->name);
982 \&
983 /* Print type of filesystem object. */
984 \&
985 if (event\->mask & IN_ISDIR)
986 printf(" [directory]\[rs]n");
987 else
988 printf(" [file]\[rs]n");
989 }
990 }
991 }
992 \&
993 int
994 main(int argc, char* argv[])
995 {
996 char buf;
997 int fd, i, poll_num;
998 int *wd;
999 nfds_t nfds;
1000 struct pollfd fds[2];
1001 \&
1002 if (argc < 2) {
1003 printf("Usage: %s PATH [PATH ...]\[rs]n", argv[0]);
1004 exit(EXIT_FAILURE);
1005 }
1006 \&
1007 printf("Press ENTER key to terminate.\[rs]n");
1008 \&
1009 /* Create the file descriptor for accessing the inotify API. */
1010 \&
1011 fd = inotify_init1(IN_NONBLOCK);
1012 if (fd == \-1) {
1013 perror("inotify_init1");
1014 exit(EXIT_FAILURE);
1015 }
1016 \&
1017 /* Allocate memory for watch descriptors. */
1018 \&
1019 wd = calloc(argc, sizeof(int));
1020 if (wd == NULL) {
1021 perror("calloc");
1022 exit(EXIT_FAILURE);
1023 }
1024 \&
1025 /* Mark directories for events
1026 \- file was opened
1027 \- file was closed */
1028 \&
1029 for (i = 1; i < argc; i++) {
1030 wd[i] = inotify_add_watch(fd, argv[i],
1031 IN_OPEN | IN_CLOSE);
1032 if (wd[i] == \-1) {
1033 fprintf(stderr, "Cannot watch \[aq]%s\[aq]: %s\[rs]n",
1034 argv[i], strerror(errno));
1035 exit(EXIT_FAILURE);
1036 }
1037 }
1038 \&
1039 /* Prepare for polling. */
1040 \&
1041 nfds = 2;
1042 \&
1043 fds[0].fd = STDIN_FILENO; /* Console input */
1044 fds[0].events = POLLIN;
1045 \&
1046 fds[1].fd = fd; /* Inotify input */
1047 fds[1].events = POLLIN;
1048 \&
1049 /* Wait for events and/or terminal input. */
1050 \&
1051 printf("Listening for events.\[rs]n");
1052 for (;;) {
1053 poll_num = poll(fds, nfds, \-1);
1054 if (poll_num == \-1) {
1055 if (errno == EINTR)
1056 continue;
1057 perror("poll");
1058 exit(EXIT_FAILURE);
1059 }
1060 \&
1061 if (poll_num > 0) {
1062 \&
1063 if (fds[0].revents & POLLIN) {
1064 \&
1065 /* Console input is available. Empty stdin and quit. */
1066 \&
1067 while (read(STDIN_FILENO, &buf, 1) > 0 && buf != \[aq]\[rs]n\[aq])
1068 continue;
1069 break;
1070 }
1071 \&
1072 if (fds[1].revents & POLLIN) {
1073 \&
1074 /* Inotify events are available. */
1075 \&
1076 handle_events(fd, wd, argc, argv);
1077 }
1078 }
1079 }
1080 \&
1081 printf("Listening for events stopped.\[rs]n");
1082 \&
1083 /* Close inotify file descriptor. */
1084 \&
1085 close(fd);
1086 \&
1087 free(wd);
1088 exit(EXIT_SUCCESS);
1089 }
1090 .EE
1091 .SH SEE ALSO
1092 .BR inotifywait (1),
1093 .BR inotifywatch (1),
1094 .BR inotify_add_watch (2),
1095 .BR inotify_init (2),
1096 .BR inotify_init1 (2),
1097 .BR inotify_rm_watch (2),
1098 .BR read (2),
1099 .BR stat (2),
1100 .BR fanotify (7)
1101 .P
1102 .I Documentation/filesystems/inotify.rst
1103 in the Linux kernel source tree