NAME¶

inotifywait, fsnotifywait - wait for changes to files using inotify or fanotify

SYNOPSIS¶

inotifywait[-hcmrPq][-e<event> ][-t<seconds> ][--format<fmt> ][--timefmt<fmt> ]<file> [ ... ]

fsnotifywait[-hcmrPqIFS][-e<event> ][-t<seconds> ][--format<fmt> ][--timefmt<fmt> ]<file> [ ... ]

DESCRIPTION¶

inotifywaitefficiently waits for changes to files using Linux'sinotify(7)interface. It is suitable for waiting for changes to files from shell scripts.It can either exit once an event occurs, or continually execute and output eventsas they occur.

fsnotifywaitis similar toinotifywaitbut it is using Linux'sfanotify(7)interface by default. If explicitly specified, it uses theinotify(7)interface.

OUTPUT¶

inotifywaitandfsnotifywaitwill output diagnostic information on standard error and event information onstandard output. The event output can be configured, but by default itconsists of lines of the following form:

watched_filename EVENT_NAMES event_filename

watched_filename

is the name of the file on which the event occurred. If the file is a directory,a trailing slash is output.

EVENT_NAMES

are the names of the inotify events which occurred, separated by commas.

event_filename

is output only when the event occurred on a directory, and in this case the nameof the file within the directory which caused this event is output.

By default, any special characters in filenames are not escaped in any way. Thiscan make the output of inotifywait difficult to parse in awk scripts or similar.The--csvand--formatoptions will be helpful in this case.

OPTIONS¶

-h, --help

Output some helpful usage information.

@<file>

When watching a directory tree recursively, exclude the specified file frombeing watched. The file must be specified with a relative or absolute pathaccording to whether a relative or absolute path is given for watcheddirectories. If a specific path is explicitly both included and excluded, itwill always be watched.

Note:If you need to watch a directory or file whose name starts with @, give theabsolute path.

--fromfile <file>

Read filenames to watch or exclude from a file, one filename per line. Iffilenames begin with @ they are excluded as described above. If <file> is `-',filenames are read from standard input. Use this option if you need to watchtoo many files to pass in as command line arguments.

-m, --monitor

Instead of exiting after receiving a single event, execute indefinitely. Thedefault behaviour is to exit after the first event occurs.

-d, --daemon

Same as --monitor, except run in the background logging events to a filethat must be specified by --outfile. Implies --syslog.

-o, --outfile <file>

Output events to <file> rather than stdout.

-s, --syslog

Output errors tosyslog(3)system log module rather than stderr.

-P, --no-dereference

Do not follow symlinks.

-r, --recursive

Watch all subdirectories of any directories passed as arguments. Watcheswill be set up recursively to an unlimited depth. Symbolic links are nottraversed. Newly created subdirectories will also be watched.

Warning:If you use this option while watching the root directoryof a large tree, it may take quite a while until all inotify watches areestablished, and events will not be received in this time. Also, since oneinotify watch will be established per subdirectory, it is possible that themaximum amount of inotify watches per user will be reached. The defaultmaximum is 8192; it can be increased by writing to/proc/sys/fs/inotify/max_user_watches.

-q, --quiet

If specified once, the program will be less verbose. Specifically, it will notstate when it has completed establishing all inotify watches.

If specified twice, the program will output nothing at all, except in the caseof fatal errors.

--exclude <pattern>

Do not process any events for the subset of files whose filenames match thespecified POSIX regular expression, case sensitive.

--excludei <pattern>

Do not process any events for the subset of files whose filenames match thespecified POSIX regular expression, case insensitive.

--include <pattern>

Process events only for the subset of files whose filenames match the specifiedPOSIX regular expression, case sensitive.

--includei <pattern>

Process events only for the subset of files whose filenames match the specifiedPOSIX regular expression, case insensitive.

-t <seconds>, --timeout <seconds>

Exit if an appropriate event has not occurred within <seconds> seconds. If<seconds> is zero (the default), wait indefinitely for an event.

-e <event>, --event <event>

Listen for specific event(s) only. The events which can be listened for arelisted in theEVENTSsection. This option can be specified more than once. If omitted, all eventsare listened for.

-c, --csv

Output in CSV (comma-separated values) format. This is useful when filenamesmay contain spaces, since in this case it is not safe to simply split the outputat each space character.

--timefmt <fmt>

Set a time format string as accepted by strftime(3) for use with the `%T' conversionin the --format option.

--no-newline

Don't print newline symbol after user-specified format in the --format option.

--format <fmt>

Output in a user-specified format, using printf-like syntax. The event stringsoutput are limited to around 4000 characters and will be truncated to this length.The following conversions are supported:

%w

This will be replaced with the name of the Watched file on which an event occurred.When an event occurs within a Watched directory or when watching with fanotify,this will be replaced with the name of the Directory in which the event occurred.

%f

When an event occurs within a Watched directory or when watching with fanotify,this will be replaced with the name of the File which caused the event to occur.Otherwise, this will be replaced with an empty string.

%e

Replaced with the Event(s) which occurred, comma-separated.

%Xe

Replaced with the Event(s) which occurred, separated by whichever character isin the place of `X'.

%T

Replaced with the current Time in the format specified by the --timefmt option,which should be a format string suitable for passing to strftime(3).

%0

Replaced with NUL.

%n

Replaced with Line Feed.

EXIT STATUS¶

0

The program executed successfully, and an event occurred which was beinglistened for.

1

An error occurred in execution of the program, or an event occurred which wasnot being listened for. The latter generally occurs if something happens whichforcibly removes the inotify watch, such as a watched file being deleted or thefilesystem containing a watched file being unmounted.

2

The-toption was used and an event did not occur in the specified interval of time.

EVENTS¶

The following events are valid for use with the-eoption:

access

A watched file or a file within a watched directory was read from.

modify

A watched file or a file within a watched directory was written to.

attrib

The metadata of a watched file or a file within a watched directory wasmodified. This includes timestamps, file permissions, extended attributes etc.

close_write

A watched file or a file within a watched directory was closed, after beingopened in writable mode. This does not necessarily imply the file was writtento.

close_nowrite

A watched file or a file within a watched directory was closed, after beingopened in read-only mode.

close

A watched file or a file within a watched directory was closed, regardless ofhow it was opened. Note that this is actually implemented simply by listeningfor bothclose_writeandclose_nowrite,hence all close events received will be output as one of these, notCLOSE.

open

A watched file or a file within a watched directory was opened.

moved_to

A file or directory was moved into a watched directory. This event occurs evenif the file is simply moved from and to the same directory.

moved_from

A file or directory was moved from a watched directory. This event occurs evenif the file is simply moved from and to the same directory.

move

A file or directory was moved from or to a watched directory. Note that this isactually implemented simply by listening for bothmoved_toandmoved_from,hence all move events received will be output as one or both of these, notMOVE.

move_self

A watched file or directory was moved. After this event, the file or directoryis no longer being watched.

create

A file or directory was created within a watched directory.

delete

A file or directory within a watched directory was deleted.

delete_self

A watched file or directory was deleted. After this event the file or directoryis no longer being watched. Note that this event can occur even if it is notexplicitly being listened for.

unmount

The filesystem on which a watched file or directory resides was unmounted.After this event the file or directory is no longer being watched. Note thatthis event can occur even if it is not explicitly being listened to.

EXAMPLES¶

% inotifywait test
Setting up watches.
Watches established.
test/ ACCESS foo

#!/bin/sh
while ! inotifywait -e modify /var/log/messages; do


  if tail -n1 /var/log/messages | grep httpd; then


    kdialog --msgbox "Apache needs love!"


  fi
done

% inotifywait -m -r --format '%:e %f' ~/test
Setting up watches.  Beware: since -r was given, this may take a while!
Watches established.
CREATE badfile
OPEN badfile
ATTRIB badfile
CLOSE_WRITE:CLOSE badfile
CREATE goodfile
OPEN goodfile
ATTRIB goodfile
CLOSE_WRITE:CLOSE goodfile
DELETE badfile

inotifywait -qmr -e 'moved_to,create' --format '%w%f%0' --no-newline ~/test |\


    while IFS= read -r -d '' file


    do
	  chmod -v a+rX "$file"


    done

CAVEATS¶

When using inotifywait, the filename that is outputted is notguaranteed to be up to date after a move because it is the inode thatis being monitored. Additionally, none of the observed operations areguaranteed to have been performed on the filename inotifywait wasinstructed to monitor in cases when the file is known by several namesin the filesystem.

BUGS¶

There are race conditions in the recursive directory watching codewhich can cause events to be missed if they occur in a directory immediatelyafter that directory is created. This is probably not fixable.

It is assumed the inotify event queue will never overflow.

AUTHORS¶

inotifywait was started by Rohan McGovern, and is currently maintained by Eric Curtin and Radu Voicilas.https://www.openhub.net/p/inotify-tools/contributors/summary gives you a more complete list of contributors.

inotifywait is part of inotify-tools. The inotify-tools website is located at:https://github.com/inotify-tools/inotify-tools/wiki

SEE ALSO¶

inotifywatch(1), strftime(3), inotify(7)