1inotifywatch(1) General Commands Manual inotifywatch(1)
2
3
4
6 inotifywatch - gather filesystem access statistics using inotify
7
8
10 inotifywatch [-hvzrqf] [-e <event> ] [-t <seconds> ] [-a <event> ] [-d
11 <event> ] <file> [ ... ]
12
13
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
19
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
27 Some diagnostic information will be output on standard error.
28
29
31 -h, --help
32 Output some helpful usage information.
33
34
35 -v, --verbose
36 Output some extra information on standard error during execu‐
37 tion.
38
39 @<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
47 Note: If you need to watch a directory or file whose name starts
48 with @, give the absolute path.
49
50 --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
57 -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
63
64 --exclude <pattern>
65 Do not process any events whose filename matches the specified
66 POSIX extended regular expression, case sensitive.
67
68
69 --excludei <pattern>
70 Do not process any events whose filename matches the specified
71 POSIX extended regular expression, case insensitive.
72
73
74 -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
80 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
89
90 -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
96
97 -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
103
104 -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
111
112 -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
119
121 0 The program executed successfully.
122
123 1 An error occurred in execution of the program.
124
125
127 The following events are valid for use with the -e option:
128
129
130 access A watched file or a file within a watched directory was read
131 from.
132
133
134 modify A watched file or a file within a watched directory was written
135 to.
136
137
138 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
142
143 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
148
149 close_nowrite
150 A watched file or a file within a watched directory was closed,
151 after being opened in read-only mode.
152
153
154 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
160
161 open A watched file or a file within a watched directory was opened.
162
163
164 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
169
170 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
175
176 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
181
182 create A file or directory was created within a watched directory.
183
184
185 delete A file or directory within a watched directory was deleted.
186
187
188 delete_self
189 A watched file or directory was deleted. After this event the
190 file or directory is no longer being watched. Note that this
191 event can occur even if it is not explicitly being listened for.
192
193
194 unmount
195 The filesystem on which a watched file or directory resides was
196 unmounted. After this event the file or directory is no longer
197 being watched. Note that this event can occur even if it is not
198 explicitly being listened to.
199
200
201
203 Watching the `~/.beagle' directory for 60 seconds:
204
205 % inotifywatch -v -e access -e modify -t 60 -r ~/.beagle
206 Establishing watches...
207 Setting up watch(es) on /home/rohan/.beagle
208 OK, /home/rohan/.beagle is now being watched.
209 Total of 302 watches.
210 Finished establishing watches, now collecting statistics.
211 Will listen for events for 60 seconds.
212 total access modify filename
213 1436 1074 362 /home/rohan/.beagle/Indexes/FileSystemIndex/PrimaryIndex/
214 1323 1053 270 /home/rohan/.beagle/Indexes/FileSystemIndex/SecondaryIndex/
215 303 116 187 /home/rohan/.beagle/Indexes/KMailIndex/PrimaryIndex/
216 261 74 187 /home/rohan/.beagle/TextCache/
217 206 0 206 /home/rohan/.beagle/Log/
218 42 0 42 /home/rohan/.beagle/Indexes/FileSystemIndex/Locks/
219 18 6 12 /home/rohan/.beagle/Indexes/FileSystemIndex/
220 12 0 12 /home/rohan/.beagle/Indexes/KMailIndex/Locks/
221 3 0 3 /home/rohan/.beagle/TextCache/54/
222 3 0 3 /home/rohan/.beagle/TextCache/bc/
223 3 0 3 /home/rohan/.beagle/TextCache/20/
224 3 0 3 /home/rohan/.beagle/TextCache/62/
225 2 2 0 /home/rohan/.beagle/Indexes/KMailIndex/SecondaryIndex/
226
227
229 There are race conditions in the recursive directory watching code
230 which can cause events to be missed if they occur in a directory imme‐
231 diately after that directory is created. This is probably not fixable.
232
233 It is assumed the inotify event queue will never overflow.
234
235
237 inotifywatch is written by Rohan McGovern <rohan@mcgovern.id.au>.
238
239 inotifywatch is part of inotify-tools. The inotify-tools website is
240 located at: http://inotify-tools.sourceforge.net/
241
242
244 inotifywait(1), inotify(7)
245
246
247
248inotifywatch 3.13 January 01, 2008 inotifywatch(1)