1inotifywait(1) General Commands Manual inotifywait(1)
2
6 inotifywait - wait for changes to files using inotify
7
10 inotifywait [-hcmrq] [-e <event> ] [-t <seconds> ] [--format <fmt> ]
11 [--timefmt <fmt> ] <file> [ ... ]
12
15 inotifywait efficiently waits for changes to files using Linux's ino‐
16 tify(7) interface. It is suitable for waiting for changes to files
17 from shell scripts. It can either exit once an event occurs, or con‐
18 tinually execute and output events as they occur.
19
22 inotifywait will output diagnostic information on standard error and
23 event information on standard output. The event output can be config‐
24 ured, but by default it consists of lines of the following form:
25 watched_filename EVENT_NAMES event_filename
27 watched_filename
30 is the name of the file on which the event occurred. If the
31 file is a directory, a trailing slash is output.
32 EVENT_NAMES
34 are the names of the inotify events which occurred, separated by
35 commas.
36 event_filename
38 is output only when the event occurred on a directory, and in
39 this case the name of the file within the directory which caused
40 this event is output.
41 By default, any special characters in filenames are not escaped
43 in any way. This can make the output of inotifywait difficult
44 to parse in awk scripts or similar. The --csv and --format
45 options will be helpful in this case.
46
49 -h, --help
50 Output some helpful usage information.
51 @<file>
53 When watching a directory tree recursively, exclude the speci‐
54 fied file from being watched. The file must be specified with a
55 relative or absolute path according to whether a relative or
56 absolute path is given for watched directories. If a specific
57 path is explicitly both included and excluded, it will always be
58 watched.
59 Note: If you need to watch a directory or file whose name starts
61 with @, give the absolute path.
62 --fromfile <file>
64 Read filenames to watch or exclude from a file, one filename per
65 line. If filenames begin with @ they are excluded as described
66 above. If <file> is `-', filenames are read from standard
67 input. Use this option if you need to watch too many files to
68 pass in as command line arguments.
69 -m, --monitor
71 Instead of exiting after receiving a single event, execute
72 indefinitely. The default behaviour is to exit after the first
73 event occurs.
74 -d, --daemon
76 Same as --monitor, except run in the background logging events
77 to a file that must be specified by --outfile. Implies --syslog.
78 -o, --outfile <file>
80 Output events to <file> rather than stdout.
81 -s, --syslog
83 Output errors to syslog(3) system log module rather than stderr.
84 -r, --recursive
86 Watch all subdirectories of any directories passed as arguments.
87 Watches will be set up recursively to an unlimited depth. Sym‐
88 bolic links are not traversed. Newly created subdirectories
89 will also be watched.
90 Warning: If you use this option while watching the root direc‐
92 tory of a large tree, it may take quite a while until all ino‐
93 tify watches are established, and events will not be received in
94 this time. Also, since one inotify watch will be established
95 per subdirectory, it is possible that the maximum amount of ino‐
96 tify watches per user will be reached. The default maximum is
97 8192; it can be increased by writing to /proc/sys/fs/ino‐
98 tify/max_user_watches.
99 -q, --quiet
102 If specified once, the program will be less verbose. Specifi‐
103 cally, it will not state when it has completed establishing all
104 inotify watches.
105 If specified twice, the program will output nothing at all,
107 except in the case of fatal errors.
108 --exclude <pattern>
111 Do not process any events whose filename matches the specified
112 POSIX extended regular expression, case sensitive.
113 --excludei <pattern>
116 Do not process any events whose filename matches the specified
117 POSIX extended regular expression, case insensitive.
118 -t <seconds>, --timeout <seconds>
121 Exit if an appropriate event has not occurred within <seconds>
122 seconds. If <seconds> is zero (the default), wait indefinitely
123 for an event.
124 -e <event>, --event <event>
127 Listen for specific event(s) only. The events which can be lis‐
128 tened for are listed in the EVENTS section. This option can be
129 specified more than once. If omitted, all events are listened
130 for.
131 -c, --csv
134 Output in CSV (comma-separated values) format. This is useful
135 when filenames may contain spaces, since in this case it is not
136 safe to simply split the output at each space character.
137 --timefmt <fmt>
140 Set a time format string as accepted by strftime(3) for use with
141 the `%T' conversion in the --format option.
142 --format <fmt>
145 Output in a user-specified format, using printf-like syntax.
146 The event strings output are limited to around 4000 characters
147 and will be truncated to this length. The following conversions
148 are supported:
149 %w This will be replaced with the name of the Watched file on which
152 an event occurred.
153 %f When an event occurs within a directory, this will be replaced
156 with the name of the File which caused the event to occur. Oth‐
157 erwise, this will be replaced with an empty string.
158 %e Replaced with the Event(s) which occurred, comma-separated.
161 %Xe Replaced with the Event(s) which occurred, separated by which‐
164 ever character is in the place of `X'.
165 %T Replaced with the current Time in the format specified by the
168 --timefmt option, which should be a format string suitable for
169 passing to strftime(3).
170
175 0 The program executed successfully, and an event occurred which
176 was being listened for.
177 1 An error occurred in execution of the program, or an event
179 occurred which was not being listened for. The latter generally
180 occurs if something happens which forcibly removes the inotify
181 watch, such as a watched file being deleted or the filesystem
182 containing a watched file being unmounted.
183 2 The -t option was used and an event did not occur in the speci‐
185 fied interval of time.
186
189 The following events are valid for use with the -e option:
190 access A watched file or a file within a watched directory was read
193 from.
194 modify A watched file or a file within a watched directory was written
197 to.
198 attrib The metadata of a watched file or a file within a watched direc‐
201 tory was modified. This includes timestamps, file permissions,
202 extended attributes etc.
203 close_write
206 A watched file or a file within a watched directory was closed,
207 after being opened in writeable mode. This does not necessarily
208 imply the file was written to.
209 close_nowrite
212 A watched file or a file within a watched directory was closed,
213 after being opened in read-only mode.
214 close A watched file or a file within a watched directory was closed,
217 regardless of how it was opened. Note that this is actually
218 implemented simply by listening for both close_write and
219 close_nowrite, hence all close events received will be output as
220 one of these, not CLOSE.
221 open A watched file or a file within a watched directory was opened.
224 moved_to
227 A file or directory was moved into a watched directory. This
228 event occurs even if the file is simply moved from and to the
229 same directory.
230 moved_from
233 A file or directory was moved from a watched directory. This
234 event occurs even if the file is simply moved from and to the
235 same directory.
236 move A file or directory was moved from or to a watched directory.
239 Note that this is actually implemented simply by listening for
240 both moved_to and moved_from, hence all close events received
241 will be output as one or both of these, not MOVE.
242 move_self
245 A watched file or directory was moved. After this event, the
246 file or directory is no longer being watched.
247 create A file or directory was created within a watched directory.
250 delete A file or directory within a watched directory was deleted.
253 delete_self
256 A watched file or directory was deleted. After this event the
257 file or directory is no longer being watched. Note that this
258 event can occur even if it is not explicitly being listened for.
259 unmount
262 The filesystem on which a watched file or directory resides was
263 unmounted. After this event the file or directory is no longer
264 being watched. Note that this event can occur even if it is not
265 explicitly being listened to.
266
270 Example 1
271 Running inotifywait at the command-line to wait for any file in the
272 `test' directory to be accessed. After running inotifywait, `cat
273 test/foo' is run in a separate console.
274 % inotifywait test
276 Setting up watches.
277 Watches established.
278 test/ ACCESS foo
279 Example 2
282 A short shell script to efficiently wait for httpd-related log messages
283 and do something appropriate.
284 #!/bin/sh
286 while inotifywait -e modify /var/log/messages; do
287 if tail -n1 /var/log/messages | grep httpd; then
288 kdialog --msgbox "Apache needs love!"
289 fi
290 done
291 Example 3
294 A custom output format is used to watch `~/test'. Meanwhile, someone
295 runs `touch ~/test/badfile; touch ~/test/goodfile; rm ~/test/badfile'
296 in another console.
297 % inotifywait -m -r --format '%:e %f' ~/test
299 Setting up watches. Beware: since -r was given, this may take a while!
300 Watches established.
301 CREATE badfile
302 OPEN badfile
303 ATTRIB badfile
304 CLOSE_WRITE:CLOSE badfile
305 CREATE goodfile
306 OPEN goodfile
307 ATTRIB goodfile
308 CLOSE_WRITE:CLOSE goodfile
309 DELETE badfile
310
314 There are race conditions in the recursive directory watching code
315 which can cause events to be missed if they occur in a directory imme‐
316 diately after that directory is created. This is probably not fixable.
317 It is assumed the inotify event queue will never overflow.
319
322 inotifywait is written and maintained by Rohan McGovern <rohan@mcgov‐
323 ern.id.au>.
324 inotifywait is part of inotify-tools. The inotify-tools website is
326 located at: http://inotify-tools.sourceforge.net/
327
330 inotifywatch(1), strftime(3), inotify(7)
331inotifywait 3.14 March 14, 2010 inotifywait(1)