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 -r, --recursive
76 Watch all subdirectories of any directories passed as arguments.
77 Watches will be set up recursively to an unlimited depth. Sym‐
78 bolic links are not traversed. Newly created subdirectories
79 will also be watched.
80 Warning: If you use this option while watching the root direc‐
82 tory of a large tree, it may take quite a while until all ino‐
83 tify watches are established, and events will not be received in
84 this time. Also, since one inotify watch will be established
85 per subdirectory, it is possible that the maximum amount of ino‐
86 tify watches per user will be reached. The default maximum is
87 8192; it can be increased by writing to /proc/sys/fs/ino‐
88 tify/max_user_watches.
89 -q, --quiet
92 If specified once, the program will be less verbose. Specifi‐
93 cally, it will not state when it has completed establishing all
94 inotify watches.
95 If specified twice, the program will output nothing at all,
97 except in the case of fatal errors.
98 --exclude <pattern>
101 Do not process any events whose filename matches the specified
102 POSIX extended regular expression, case sensitive.
103 --excludei <pattern>
106 Do not process any events whose filename matches the specified
107 POSIX extended regular expression, case insensitive.
108 -t <seconds>, --timeout <seconds>
111 Listen for an event for the specified amount of seconds, exiting
112 if an event has not occurred in that time.
113 -e <event>, --event <event>
116 Listen for specific event(s) only. The events which can be lis‐
117 tened for are listed in the EVENTS section. This option can be
118 specified more than once. If omitted, all events are listened
119 for.
120 -c, --csv
123 Output in CSV (comma-separated values) format. This is useful
124 when filenames may contain spaces, since in this case it is not
125 safe to simply split the output at each space character.
126 --timefmt <fmt>
129 Set a time format string as accepted by strftime(3) for use with
130 the `%T' conversion in the --format option.
131 --format <fmt>
134 Output in a user-specified format, using printf-like syntax.
135 The event strings output are limited to around 4000 characters
136 and will be truncated to this length. The following conversions
137 are supported:
138 %w This will be replaced with the name of the Watched file on which
141 an event occurred.
142 %f When an event occurs within a directory, this will be replaced
145 with the name of the File which caused the event to occur. Oth‐
146 erwise, this will be replaced with an empty string.
147 %e Replaced with the Event(s) which occurred, comma-separated.
150 %Xe Replaced with the Event(s) which occurred, separated by which‐
153 ever character is in the place of `X'.
154 %T Replaced with the current Time in the format specified by the
157 --timefmt option, which should be a format string suitable for
158 passing to strftime(3).
159
164 0 The program executed successfully, and an event occurred which
165 was being listened for.
166 1 An error occurred in execution of the program, or an event
168 occurred which was not being listened for. The latter generally
169 occurs if something happens which forcibly removes the inotify
170 watch, such as a watched file being deleted or the filesystem
171 containing a watched file being unmounted.
172 2 The -t option was used and an event did not occur in the speci‐
174 fied interval of time.
175
178 The following events are valid for use with the -e option:
179 access A watched file or a file within a watched directory was read
182 from.
183 modify A watched file or a file within a watched directory was written
186 to.
187 attrib The metadata of a watched file or a file within a watched direc‐
190 tory was modified. This includes timestamps, file permissions,
191 extended attributes etc.
192 close_write
195 A watched file or a file within a watched directory was closed,
196 after being opened in writeable mode. This does not necessarily
197 imply the file was written to.
198 close_nowrite
201 A watched file or a file within a watched directory was closed,
202 after being opened in read-only mode.
203 close A watched file or a file within a watched directory was closed,
206 regardless of how it was opened. Note that this is actually
207 implemented simply by listening for both close_write and
208 close_nowrite, hence all close events received will be output as
209 one of these, not CLOSE.
210 open A watched file or a file within a watched directory was opened.
213 moved_to
216 A file or directory was moved into a watched directory. This
217 event occurs even if the file is simply moved from and to the
218 same directory.
219 moved_from
222 A file or directory was moved from a watched directory. This
223 event occurs even if the file is simply moved from and to the
224 same directory.
225 move A file or directory was moved from or to a watched directory.
228 Note that this is actually implemented simply by listening for
229 both moved_to and moved_from, hence all close events received
230 will be output as one or both of these, not MOVE.
231 create A file or directory was created within a watched directory.
234 delete A file or directory within a watched directory was deleted.
237 delete_self
240 A watched file or directory was deleted. After this event the
241 file or directory is no longer being watched. Note that this
242 event can occur even if it is not explicitly being listened for.
243 unmount
246 The filesystem on which a watched file or directory resides was
247 unmounted. After this event the file or directory is no longer
248 being watched. Note that this event can occur even if it is not
249 explicitly being listened to.
250
254 Example 1
255 Running inotifywait at the command-line to wait for any file in the
256 `test' directory to be accessed. After running inotifywait, `cat
257 test/foo' is run in a separate console.
258 % inotifywait test
260 Setting up watches.
261 Watches established.
262 test/ ACCESS foo
263 Example 2
266 A short shell script to efficiently wait for httpd-related log messages
267 and do something appropriate.
268 #!/bin/sh
270 while inotifywait -e modify /var/log/messages; do
271 if tail -n1 /var/log/messages | grep httpd; then
272 kdialog --msgbox "Apache needs love!"
273 fi
274 done
275 Example 3
278 A custom output format is used to watch `~/test'. Meanwhile, someone
279 runs `touch ~/test/badfile; touch ~/test/goodfile; rm ~/test/badfile'
280 in another console.
281 % inotifywait -m -r --format '%:e %f' ~/test
283 Setting up watches. Beware: since -r was given, this may take a while!
284 Watches established.
285 CREATE badfile
286 OPEN badfile
287 ATTRIB badfile
288 CLOSE_WRITE:CLOSE badfile
289 CREATE goodfile
290 OPEN goodfile
291 ATTRIB goodfile
292 CLOSE_WRITE:CLOSE goodfile
293 DELETE badfile
294
298 There are race conditions in the recursive directory watching code
299 which can cause events to be missed if they occur in a directory imme‐
300 diately after that directory is created. This is probably not fixable.
301 It is assumed the inotify event queue will never overflow.
303
306 inotifywait is written and maintained by Rohan McGovern <rohan@mcgov‐
307 ern.id.au>.
308 inotifywait is part of inotify-tools. The inotify-tools website is
310 located at: http://inotify-tools.sourceforge.net/
311
314 inotifywatch(1), strftime(3), inotify(7)
315inotifywait 3.13 January 01, 2008 inotifywait(1)