1inotifywait(1) General Commands Manual inotifywait(1)
2
6 inotifywait, fsnotifywait - wait for changes to files using inotify or
7 fanotify
8
11 inotifywait [-hcmrPq] [-e <event> ] [-t <seconds> ] [--format <fmt> ]
12 [--timefmt <fmt> ] <file> [ ... ]
13 fsnotifywait [-hcmrPqIFS] [-e <event> ] [-t <seconds> ] [--format <fmt>
15 ] [--timefmt <fmt> ] <file> [ ... ]
16
20 inotifywait efficiently waits for changes to files using Linux's ino‐
21 tify(7) interface. It is suitable for waiting for changes to files
22 from shell scripts. It can either exit once an event occurs, or con‐
23 tinually execute and output events as they occur.
24 fsnotifywait is similar to inotifywait but it is using Linux's fan‐
26 otify(7) interface by default. If explicitly specified, it uses the in‐
27 otify(7) interface.
28
31 inotifywait and fsnotifywait will output diagnostic information on
32 standard error and event information on standard output. The event
33 output can be configured, but by default it consists of lines of the
34 following form:
35 watched_filename EVENT_NAMES event_filename
37 watched_filename
40 is the name of the file on which the event occurred. If the
41 file is a directory, a trailing slash is output.
42 EVENT_NAMES
44 are the names of the inotify events which occurred, separated by
45 commas.
46 event_filename
48 is output only when the event occurred on a directory, and in
49 this case the name of the file within the directory which caused
50 this event is output.
51 By default, any special characters in filenames are not escaped
53 in any way. This can make the output of inotifywait difficult
54 to parse in awk scripts or similar. The --csv and --format op‐
55 tions will be helpful in this case.
56
59 -h, --help
60 Output some helpful usage information.
61 @<file>
63 When watching a directory tree recursively, exclude the speci‐
64 fied file from being watched. The file must be specified with a
65 relative or absolute path according to whether a relative or ab‐
66 solute path is given for watched directories. If a specific
67 path is explicitly both included and excluded, it will always be
68 watched.
69 Note: If you need to watch a directory or file whose name starts
71 with @, give the absolute path.
72 --fromfile <file>
74 Read filenames to watch or exclude from a file, one filename per
75 line. If filenames begin with @ they are excluded as described
76 above. If <file> is `-', filenames are read from standard in‐
77 put. Use this option if you need to watch too many files to
78 pass in as command line arguments.
79 -m, --monitor
81 Instead of exiting after receiving a single event, execute in‐
82 definitely. The default behaviour is to exit after the first
83 event occurs.
84 -d, --daemon
86 Same as --monitor, except run in the background logging events
87 to a file that must be specified by --outfile. Implies --syslog.
88 -o, --outfile <file>
90 Output events to <file> rather than stdout.
91 -s, --syslog
93 Output errors to syslog(3) system log module rather than stderr.
94 -P, --no-dereference
96 Do not follow symlinks.
97 -r, --recursive
99 Watch all subdirectories of any directories passed as arguments.
100 Watches will be set up recursively to an unlimited depth. Sym‐
101 bolic links are not traversed. Newly created subdirectories
102 will also be watched.
103 Warning: If you use this option while watching the root direc‐
105 tory of a large tree, it may take quite a while until all ino‐
106 tify watches are established, and events will not be received in
107 this time. Also, since one inotify watch will be established
108 per subdirectory, it is possible that the maximum amount of ino‐
109 tify watches per user will be reached. The default maximum is
110 8192; it can be increased by writing to /proc/sys/fs/ino‐
111 tify/max_user_watches.
112 -q, --quiet
115 If specified once, the program will be less verbose. Specifi‐
116 cally, it will not state when it has completed establishing all
117 inotify watches.
118 If specified twice, the program will output nothing at all, ex‐
120 cept in the case of fatal errors.
121 --exclude <pattern>
124 Do not process any events for the subset of files whose file‐
125 names match the specified POSIX regular expression, case sensi‐
126 tive.
127 --excludei <pattern>
130 Do not process any events for the subset of files whose file‐
131 names match the specified POSIX regular expression, case insen‐
132 sitive.
133 --include <pattern>
136 Process events only for the subset of files whose filenames
137 match the specified POSIX regular expression, case sensitive.
138 --includei <pattern>
141 Process events only for the subset of files whose filenames
142 match the specified POSIX regular expression, case insensitive.
143 -t <seconds>, --timeout <seconds>
146 Exit if an appropriate event has not occurred within <seconds>
147 seconds. If <seconds> is zero (the default), wait indefinitely
148 for an event.
149 -e <event>, --event <event>
152 Listen for specific event(s) only. The events which can be lis‐
153 tened for are listed in the EVENTS section. This option can be
154 specified more than once. If omitted, all events are listened
155 for.
156 -c, --csv
159 Output in CSV (comma-separated values) format. This is useful
160 when filenames may contain spaces, since in this case it is not
161 safe to simply split the output at each space character.
162 --timefmt <fmt>
165 Set a time format string as accepted by strftime(3) for use with
166 the `%T' conversion in the --format option.
167 --no-newline
170 Don't print newline symbol after user-specified format in the
171 --format option.
172 --format <fmt>
175 Output in a user-specified format, using printf-like syntax.
176 The event strings output are limited to around 4000 characters
177 and will be truncated to this length. The following conversions
178 are supported:
179 %w This will be replaced with the name of the Watched file on which
182 an event occurred. When an event occurs within a Watched direc‐
183 tory or when watching with fanotify, this will be replaced with
184 the name of the Directory in which the event occurred.
185 %f When an event occurs within a Watched directory or when watching
188 with fanotify, this will be replaced with the name of the File
189 which caused the event to occur. Otherwise, this will be re‐
190 placed with an empty string.
191 %e Replaced with the Event(s) which occurred, comma-separated.
194 %Xe Replaced with the Event(s) which occurred, separated by which‐
197 ever character is in the place of `X'.
198 %T Replaced with the current Time in the format specified by the
201 --timefmt option, which should be a format string suitable for
202 passing to strftime(3).
203 %0 Replaced with NUL.
206 %n Replaced with Line Feed.
209 fsnotifywait
212 The following additional options are available:
213 -I, --inotify
215 Watch using inotify.
216 -F, --fanotify
219 Watch using fanotify (default). fanotify support for reporting
220 events with inotify compatible information was added in kernel
221 v5.9. With older kernels the command will fail. As of kernel
222 v5.12, fanotify requires admin privileges.
223 -S, --filesystem
226 Watch entire filesystem of any directories passed as arguments
227 using fanotify.
228
233 0 The program executed successfully, and an event occurred which
234 was being listened for.
235 1 An error occurred in execution of the program, or an event oc‐
237 curred which was not being listened for. The latter generally
238 occurs if something happens which forcibly removes the inotify
239 watch, such as a watched file being deleted or the filesystem
240 containing a watched file being unmounted.
241 2 The -t option was used and an event did not occur in the speci‐
243 fied interval of time.
244
247 The following events are valid for use with the -e option:
248 access A watched file or a file within a watched directory was read
251 from.
252 modify A watched file or a file within a watched directory was written
255 to.
256 attrib The metadata of a watched file or a file within a watched direc‐
259 tory was modified. This includes timestamps, file permissions,
260 extended attributes etc.
261 close_write
264 A watched file or a file within a watched directory was closed,
265 after being opened in writable mode. This does not necessarily
266 imply the file was written to.
267 close_nowrite
270 A watched file or a file within a watched directory was closed,
271 after being opened in read-only mode.
272 close A watched file or a file within a watched directory was closed,
275 regardless of how it was opened. Note that this is actually im‐
276 plemented simply by listening for both close_write and
277 close_nowrite, hence all close events received will be output as
278 one of these, not CLOSE.
279 open A watched file or a file within a watched directory was opened.
282 moved_to
285 A file or directory was moved into a watched directory. This
286 event occurs even if the file is simply moved from and to the
287 same directory.
288 moved_from
291 A file or directory was moved from a watched directory. This
292 event occurs even if the file is simply moved from and to the
293 same directory.
294 move A file or directory was moved from or to a watched directory.
297 Note that this is actually implemented simply by listening for
298 both moved_to and moved_from, hence all move events received
299 will be output as one or both of these, not MOVE.
300 move_self
303 A watched file or directory was moved. After this event, the
304 file or directory is no longer being watched.
305 create A file or directory was created within a watched directory.
308 delete A file or directory within a watched directory was deleted.
311 delete_self
314 A watched file or directory was deleted. After this event the
315 file or directory is no longer being watched. Note that this
316 event can occur even if it is not explicitly being listened for.
317 unmount
320 The filesystem on which a watched file or directory resides was
321 unmounted. After this event the file or directory is no longer
322 being watched. Note that this event can occur even if it is not
323 explicitly being listened to.
324
328 Example 1
329 Running inotifywait at the command-line to wait for any file in the
330 `test' directory to be accessed. After running inotifywait, `cat
331 test/foo' is run in a separate console.
332 % inotifywait test
334 Setting up watches.
335 Watches established.
336 test/ ACCESS foo
337 Example 2
340 A short shell script to efficiently wait for httpd-related log messages
341 and do something appropriate.
342 #!/bin/sh
344 while ! inotifywait -e modify /var/log/messages; do
345 if tail -n1 /var/log/messages | grep httpd; then
346 kdialog --msgbox "Apache needs love!"
347 fi
348 done
349 Example 3
352 A custom output format is used to watch `~/test'. Meanwhile, someone
353 runs `touch ~/test/badfile; touch ~/test/goodfile; rm ~/test/badfile'
354 in another console.
355 % inotifywait -m -r --format '%:e %f' ~/test
357 Setting up watches. Beware: since -r was given, this may take a while!
358 Watches established.
359 CREATE badfile
360 OPEN badfile
361 ATTRIB badfile
362 CLOSE_WRITE:CLOSE badfile
363 CREATE goodfile
364 OPEN goodfile
365 ATTRIB goodfile
366 CLOSE_WRITE:CLOSE goodfile
367 DELETE badfile
368 Example 4
371 Enforce file permissions in directory `~/test'
372 inotifywait -qmr -e 'moved_to,create' --format '%w%f%0' --no-newline ~/test |\
374 while IFS= read -r -d '' file
375 do
376 chmod -v a+rX "$file"
377 done
378
381 When using inotifywait, the filename that is outputted is not guaran‐
382 teed to be up to date after a move because it is the inode that is be‐
383 ing monitored. Additionally, none of the observed operations are guar‐
384 anteed to have been performed on the filename inotifywait was in‐
385 structed to monitor in cases when the file is known by several names in
386 the filesystem.
387
390 There are race conditions in the recursive directory watching code
391 which can cause events to be missed if they occur in a directory imme‐
392 diately after that directory is created. This is probably not fixable.
393 It is assumed the inotify event queue will never overflow.
395
398 inotifywait was started by Rohan McGovern, and is currently maintained
399 by Eric Curtin and Radu Voicilas. https://www.openhub.net/p/inotify-
400 tools/contributors/summary gives you a more complete list of contribu‐
401 tors.
402 inotifywait is part of inotify-tools. The inotify-tools website is lo‐
404 cated at: https://github.com/inotify-tools/inotify-tools/wiki
405
408 inotifywatch(1), strftime(3), inotify(7)
409inotifywait 3.22.1.0 2022-01-18 inotifywait(1)