1inotifywatch(1) General Commands Manual inotifywatch(1)
2
6 inotifywatch - gather filesystem access statistics using inotify
7
10 inotifywatch [-hvzrqf] [-e <event> ] [-t <seconds> ] [-a <event> ] [-d
11 <event> ] <file> [ ... ]
12
15 inotifywatch listens for filesystem events using Linux's inotify(7)
16 interface, then outputs a summary count of the events received on each
17 file or directory.
18
21 inotifywatch will output a table on standard out with one column for
22 each type of event and one row for each watched file or directory. The
23 table will show the amount of times each event occurred for each
24 watched file or directory. Output can be sorted by a particular event
25 using the -a or -d options.
26 Some diagnostic information will be output on standard error.
28
31 -h, --help
32 Output some helpful usage information.
33 -v, --verbose
36 Output some extra information on standard error during execu‐
37 tion.
38 @<file>
40 When watching a directory tree recursively, exclude the speci‐
41 fied file from being watched. The file must be specified with a
42 relative or absolute path according to whether a relative or
43 absolute path is given for watched directories. If a specific
44 path is explicitly both included and excluded, it will always be
45 watched.
46 Note: If you need to watch a directory or file whose name starts
48 with @, give the absolute path.
49 --fromfile <file>
51 Read filenames to watch or exclude from a file, one filename per
52 line. If filenames begin with @ they are excluded as described
53 above. If <file> is `-', filenames are read from standard
54 input. Use this option if you need to watch too many files to
55 pass in as command line arguments.
56 -z, --zero
58 Output table rows and columns even if all elements are zero. By
59 default, rows and columns are only output if they contain non-
60 zero elements. Using this option when watching for every event
61 on a lot of files can result in a lot of output!
62 --exclude <pattern>
65 Do not process any events whose filename matches the specified
66 POSIX extended regular expression, case sensitive.
67 --excludei <pattern>
70 Do not process any events whose filename matches the specified
71 POSIX extended regular expression, case insensitive.
72 -r, --recursive
75 Watch all subdirectories of any directories passed as arguments.
76 Watches will be set up recursively to an unlimited depth. Sym‐
77 bolic links are not traversed. If new directories are created
78 within watched directories they will automatically be watched.
79 Warning: If you use this option while watching the root direc‐
81 tory of a large tree, it may take quite a while until all ino‐
82 tify watches are established, and events will not be received in
83 this time. Also, since one inotify watch will be established
84 per subdirectory, it is possible that the maximum amount of ino‐
85 tify watches per user will be reached. The default maximum is
86 8192; it can be increased by writing to /proc/sys/fs/ino‐
87 tify/max_user_watches.
88 -t <seconds>, --timeout <seconds>
91 Listen only for the specified amount of seconds. If not speci‐
92 fied, inotifywatch will gather statistics until receiving an
93 interrupt signal by (for example) pressing CONTROL-C at the con‐
94 sole.
95 -e <event>, --event <event>
98 Listen for specific event(s) only. The events which can be lis‐
99 tened for are listed in the EVENTS section. This option can be
100 specified more than once. If omitted, all events are listened
101 for.
102 -a <event>, --ascending <event>
105 Sort output ascending by event counts for the specified event.
106 Sortable events include `total' and all the events listed in the
107 EVENTS section except `move' and `close' (you must use
108 `moved_to', `moved_from', `close_write' or `close_nowrite'
109 instead). The default is to sort descending by `total'.
110 -d <event>, --descending <event>
113 Sort output descending by event counts for the specified event.
114 Sortable events include `total' and all the events listed in the
115 EVENTS section except `move' and `close' (you must use
116 `moved_to', `moved_from', `close_write' or `close_nowrite'
117 instead). The default is to sort descending by `total'.
118
121 0 The program executed successfully.
122 1 An error occurred in execution of the program.
124
127 The following events are valid for use with the -e option:
128 access A watched file or a file within a watched directory was read
131 from.
132 modify A watched file or a file within a watched directory was written
135 to.
136 attrib The metadata of a watched file or a file within a watched direc‐
139 tory was modified. This includes timestamps, file permissions,
140 extended attributes etc.
141 close_write
144 A watched file or a file within a watched directory was closed,
145 after being opened in writeable mode. This does not necessarily
146 imply the file was written to.
147 close_nowrite
150 A watched file or a file within a watched directory was closed,
151 after being opened in read-only mode.
152 close A watched file or a file within a watched directory was closed,
155 regardless of how it was opened. Note that this is actually
156 implemented simply by listening for both close_write and
157 close_nowrite, hence all close events received will be output as
158 one of these, not CLOSE.
159 open A watched file or a file within a watched directory was opened.
162 moved_to
165 A file or directory was moved into a watched directory. This
166 event occurs even if the file is simply moved from and to the
167 same directory.
168 moved_from
171 A file or directory was moved from a watched directory. This
172 event occurs even if the file is simply moved from and to the
173 same directory.
174 move A file or directory was moved from or to a watched directory.
177 Note that this is actually implemented simply by listening for
178 both moved_to and moved_from, hence all close events received
179 will be output as one or both of these, not MOVE.
180 move_self
183 A watched file or directory was moved. After this event, the
184 file or directory is no longer being watched.
185 create A file or directory was created within a watched directory.
188 delete A file or directory within a watched directory was deleted.
191 delete_self
194 A watched file or directory was deleted. After this event the
195 file or directory is no longer being watched. Note that this
196 event can occur even if it is not explicitly being listened for.
197 unmount
200 The filesystem on which a watched file or directory resides was
201 unmounted. After this event the file or directory is no longer
202 being watched. Note that this event can occur even if it is not
203 explicitly being listened to.
204
208 Watching the `~/.beagle' directory for 60 seconds:
209 % inotifywatch -v -e access -e modify -t 60 -r ~/.beagle
211 Establishing watches...
212 Setting up watch(es) on /home/rohan/.beagle
213 OK, /home/rohan/.beagle is now being watched.
214 Total of 302 watches.
215 Finished establishing watches, now collecting statistics.
216 Will listen for events for 60 seconds.
217 total access modify filename
218 1436 1074 362 /home/rohan/.beagle/Indexes/FileSystemIndex/PrimaryIndex/
219 1323 1053 270 /home/rohan/.beagle/Indexes/FileSystemIndex/SecondaryIndex/
220 303 116 187 /home/rohan/.beagle/Indexes/KMailIndex/PrimaryIndex/
221 261 74 187 /home/rohan/.beagle/TextCache/
222 206 0 206 /home/rohan/.beagle/Log/
223 42 0 42 /home/rohan/.beagle/Indexes/FileSystemIndex/Locks/
224 18 6 12 /home/rohan/.beagle/Indexes/FileSystemIndex/
225 12 0 12 /home/rohan/.beagle/Indexes/KMailIndex/Locks/
226 3 0 3 /home/rohan/.beagle/TextCache/54/
227 3 0 3 /home/rohan/.beagle/TextCache/bc/
228 3 0 3 /home/rohan/.beagle/TextCache/20/
229 3 0 3 /home/rohan/.beagle/TextCache/62/
230 2 2 0 /home/rohan/.beagle/Indexes/KMailIndex/SecondaryIndex/
231
234 There are race conditions in the recursive directory watching code
235 which can cause events to be missed if they occur in a directory imme‐
236 diately after that directory is created. This is probably not fixable.
237 It is assumed the inotify event queue will never overflow.
239
242 inotifywatch is written by Rohan McGovern <rohan@mcgovern.id.au>.
243 inotifywatch is part of inotify-tools. The inotify-tools website is
245 located at: http://inotify-tools.sourceforge.net/
246
249 inotifywait(1), inotify(7)
250inotifywatch 3.14 March 14, 2010 inotifywatch(1)