1inotifywatch(1) General Commands Manual inotifywatch(1)
2
6 inotifywatch, fsnotifywatch - gather filesystem access statistics using
7 inotify or fanotify
8
11 inotifywatch [-hvzrPqf] [-e <event> ] [-t <seconds> ] [-a <event> ] [-d
12 <event> ] <file> [ ... ]
13 fsnotifywatch [-hvzrPqfIFS] [-e <event> ] [-t <seconds> ] [-a <event> ]
15 [-d <event> ] <file> [ ... ]
16
19 inotifywatch listens for filesystem events using Linux's inotify(7) in‐
20 terface, then outputs a summary count of the events received on each
21 file or directory.
22 fsnotifywatch is similar to inotifywatch but it is using Linux's fan‐
24 otify(7) interface by default. If explicitly specified, it uses the in‐
25 otify(7) interface.
26
29 inotifywatch and fsnotifywatch will output a table on standard out with
30 one column for each type of event and one row for each watched file or
31 directory. The table will show the amount of times each event occurred
32 for each watched file or directory. Output can be sorted by a particu‐
33 lar event using the -a or -d options.
34 Some diagnostic information will be output on standard error.
36
39 -h, --help
40 Output some helpful usage information.
41 -v, --verbose
44 Output some extra information on standard error during execu‐
45 tion.
46 @<file>
48 When watching a directory tree recursively, exclude the speci‐
49 fied file from being watched. The file must be specified with a
50 relative or absolute path according to whether a relative or ab‐
51 solute path is given for watched directories. If a specific
52 path is explicitly both included and excluded, it will always be
53 watched.
54 Note: If you need to watch a directory or file whose name starts
56 with @, give the absolute path.
57 --fromfile <file>
59 Read filenames to watch or exclude from a file, one filename per
60 line. If filenames begin with @ they are excluded as described
61 above. If <file> is `-', filenames are read from standard in‐
62 put. Use this option if you need to watch too many files to
63 pass in as command line arguments.
64 -z, --zero
66 Output table rows and columns even if all elements are zero. By
67 default, rows and columns are only output if they contain non-
68 zero elements. Using this option when watching for every event
69 on a lot of files can result in a lot of output!
70 --exclude <pattern>
73 Do not process any events for the subset of files whose file‐
74 names match the specified POSIX regular expression, case sensi‐
75 tive.
76 --excludei <pattern>
79 Do not process any events for the subset of files whose file‐
80 names match the specified POSIX regular expression, case insen‐
81 sitive.
82 --include <pattern>
85 Process events only for the subset of files whose filenames
86 match the specified POSIX regular expression, case sensitive.
87 --includei <pattern>
90 Process events only for the subset of files whose filenames
91 match the specified POSIX regular expression, case insensitive.
92 -r, --recursive
95 Watch all subdirectories of any directories passed as arguments.
96 Watches will be set up recursively to an unlimited depth. Sym‐
97 bolic links are not traversed. If new directories are created
98 within watched directories they will automatically be watched.
99 Warning: If you use this option while watching the root direc‐
101 tory of a large tree, it may take quite a while until all ino‐
102 tify watches are established, and events will not be received in
103 this time. Also, since one inotify watch will be established
104 per subdirectory, it is possible that the maximum amount of ino‐
105 tify watches per user will be reached. The default maximum is
106 8192; it can be increased by writing to /proc/sys/fs/ino‐
107 tify/max_user_watches.
108 -P, --no-dereference
111 Do not follow symlinks.
112 -t <seconds>, --timeout <seconds>
115 Listen only for the specified amount of seconds. If not speci‐
116 fied, inotifywatch will gather statistics until receiving an in‐
117 terrupt signal by (for example) pressing CONTROL-C at the con‐
118 sole.
119 -e <event>, --event <event>
122 Listen for specific event(s) only. The events which can be lis‐
123 tened for are listed in the EVENTS section. This option can be
124 specified more than once. If omitted, all events are listened
125 for.
126 -a <event>, --ascending <event>
129 Sort output ascending by event counts for the specified event.
130 Sortable events include `total' and all the events listed in the
131 EVENTS section except `move' and `close' (you must use
132 `moved_to', `moved_from', `close_write' or `close_nowrite' in‐
133 stead). The default is to sort descending by `total'.
134 -d <event>, --descending <event>
137 Sort output descending by event counts for the specified event.
138 Sortable events include `total' and all the events listed in the
139 EVENTS section except `move' and `close' (you must use
140 `moved_to', `moved_from', `close_write' or `close_nowrite' in‐
141 stead). The default is to sort descending by `total'.
142
145 0 The program executed successfully.
146 1 An error occurred in execution of the program.
148
151 The following events are valid for use with the -e option:
152 access A watched file or a file within a watched directory was read
155 from.
156 modify A watched file or a file within a watched directory was written
159 to.
160 attrib The metadata of a watched file or a file within a watched direc‐
163 tory was modified. This includes timestamps, file permissions,
164 extended attributes etc.
165 close_write
168 A watched file or a file within a watched directory was closed,
169 after being opened in writable mode. This does not necessarily
170 imply the file was written to.
171 close_nowrite
174 A watched file or a file within a watched directory was closed,
175 after being opened in read-only mode.
176 close A watched file or a file within a watched directory was closed,
179 regardless of how it was opened. Note that this is actually im‐
180 plemented simply by listening for both close_write and
181 close_nowrite, hence all close events received will be output as
182 one of these, not CLOSE.
183 open A watched file or a file within a watched directory was opened.
186 moved_to
189 A file or directory was moved into a watched directory. This
190 event occurs even if the file is simply moved from and to the
191 same directory.
192 moved_from
195 A file or directory was moved from a watched directory. This
196 event occurs even if the file is simply moved from and to the
197 same directory.
198 move A file or directory was moved from or to a watched directory.
201 Note that this is actually implemented simply by listening for
202 both moved_to and moved_from, hence all close events received
203 will be output as one or both of these, not MOVE.
204 move_self
207 A watched file or directory was moved. After this event, the
208 file or directory is no longer being watched.
209 create A file or directory was created within a watched directory.
212 delete A file or directory within a watched directory was deleted.
215 delete_self
218 A watched file or directory was deleted. After this event the
219 file or directory is no longer being watched. Note that this
220 event can occur even if it is not explicitly being listened for.
221 unmount
224 The filesystem on which a watched file or directory resides was
225 unmounted. After this event the file or directory is no longer
226 being watched. Note that this event can occur even if it is not
227 explicitly being listened to.
228 fsnotifywatch
231 The following additional options are available:
232 -I, --inotify
235 Watch using inotify.
236 -F, --fanotify
239 Watch using fanotify (default). fanotify support for reporting
240 events with inotify compatible information was added in kernel
241 v5.9. With older kernels the command will fail. As of kernel
242 v5.12, fanotify requires admin privileges.
243 -S, --filesystem
246 Watch entire filesystem of any directories passed as arguments
247 using fanotify.
248
252 Watching the `~/.beagle' directory for 60 seconds:
253 % inotifywatch -v -e access -e modify -t 60 -r ~/.beagle
255 Establishing watches...
256 Setting up watch(es) on /home/rohan/.beagle
257 OK, /home/rohan/.beagle is now being watched.
258 Total of 302 watches.
259 Finished establishing watches, now collecting statistics.
260 Will listen for events for 60 seconds.
261 total access modify filename
262 1436 1074 362 /home/rohan/.beagle/Indexes/FileSystemIndex/PrimaryIndex/
263 1323 1053 270 /home/rohan/.beagle/Indexes/FileSystemIndex/SecondaryIndex/
264 303 116 187 /home/rohan/.beagle/Indexes/KMailIndex/PrimaryIndex/
265 261 74 187 /home/rohan/.beagle/TextCache/
266 206 0 206 /home/rohan/.beagle/Log/
267 42 0 42 /home/rohan/.beagle/Indexes/FileSystemIndex/Locks/
268 18 6 12 /home/rohan/.beagle/Indexes/FileSystemIndex/
269 12 0 12 /home/rohan/.beagle/Indexes/KMailIndex/Locks/
270 3 0 3 /home/rohan/.beagle/TextCache/54/
271 3 0 3 /home/rohan/.beagle/TextCache/bc/
272 3 0 3 /home/rohan/.beagle/TextCache/20/
273 3 0 3 /home/rohan/.beagle/TextCache/62/
274 2 2 0 /home/rohan/.beagle/Indexes/KMailIndex/SecondaryIndex/
275
278 When using inotifywatch, the filename that is outputted is not guaran‐
279 teed to be up to date after a move because it is the inode that is be‐
280 ing monitored. Additionally, none of the observed operations are guar‐
281 anteed to have been performed on the filename inotifywatch was in‐
282 structed to monitor in cases when the file is known by several names in
283 the filesystem.
284
287 There are race conditions in the recursive directory watching code
288 which can cause events to be missed if they occur in a directory imme‐
289 diately after that directory is created. This is probably not fixable.
290 It is assumed the inotify event queue will never overflow.
292
295 inotifywatch was started by Rohan McGovern, and is currently maintained
296 by Eric Curtin and Radu Voicilas. https://www.openhub.net/p/inotify-
297 tools/contributors/summary gives you a more complete list of contribu‐
298 tors.
299 inotifywatch is part of inotify-tools. The inotify-tools website is
301 located at: https://github.com/inotify-tools/inotify-tools/wiki
302
305 inotifywait(1), inotify(7)
306inotifywatch 3.22.1.0 2022-01-18 inotifywatch(1)