NAME

       inotifywait - wait for changes to files using inotify

SYNOPSIS

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

DESCRIPTION

       inotifywait efficiently  waits  for  changes  to  files  using  Linux’s
       inotify(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 events as they occur.

OUTPUT

       inotifywait  will  output  diagnostic information on standard error and
       event  information  on  standard  output.   The  event  output  can  be
       configured, but by default it consists 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 name of the file within the directory which caused
              this event is output.

              By  default, any special characters in filenames are not escaped
              in any way.  This can make the output of  inotifywait  difficult
              to  parse  in  awk  scripts  or similar.  The --csv and --format
              options 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  from being watched.  The file must be specified
              with a relative or absolute path according to whether a relative
              or  absolute  path  is  given  for  watched  directories.   If a
              specific path is explicitly both included and excluded, it  will
              always be watched.

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

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

       -m, --monitor
              Instead of exiting  after  receiving  a  single  event,  execute
              indefinitely.   The default behaviour is to exit after the first
              event occurs.

       -r, --recursive
              Watch all subdirectories of any directories passed as arguments.
              Watches  will  be  set  up  recursively  to  an unlimited depth.
              Symbolic links are not traversed.  Newly created  subdirectories
              will also be watched.

              Warning:  If  you  use  this  option  while  watching  the  root
              directory of a large tree, it may take quite a while  until  all
              inotify watches are established, and events will not be received
              in this time.  Also, since one inotify watch will be established
              per  subdirectory,  it  is  possible  that the maximum amount of
              inotify watches per user will be reached.  The  default  maximum
              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   not  state  when  it  has  completed
              establishing all inotify watches.

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

       --exclude <pattern>
              Do  not  process any events whose filename matches the specified
              POSIX extended regular expression, case sensitive.

       --excludei <pattern>
              Do not process any events whose filename matches  the  specified
              POSIX extended regular expression, case insensitive.

       -t <seconds>, --timeout <seconds>
              Listen for an event for the specified amount of seconds, exiting
              if an event has not occurred in that time.

       -e <event>, --event <event>
              Listen for specific event(s) only.   The  events  which  can  be
              listened  for are listed in the EVENTS section.  This option can
              be specified  more  than  once.   If  omitted,  all  events  are
              listened for.

       -c, --csv
              Output  in  CSV (comma-separated values) format.  This is useful
              when filenames may contain spaces, since in this case it is  not
              safe to simply split the output at each space character.

       --timefmt <fmt>
              Set a time format string as accepted by strftime(3) for use with
              the ‘%T’ conversion in the --format option.

       --format <fmt>
              Output in a user-specified  format,  using  printf-like  syntax.
              The  event  strings output 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.

       %f     When an event occurs within a directory, 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 is in 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).

EXIT STATUS

       0      The  program  executed successfully, and an event occurred which
              was being listened for.

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

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

EVENTS

       The following events are valid for use with the -e option:

       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  was  modified.   This   includes   timestamps,   file
              permissions, extended attributes etc.

       close_write
              A  watched file or a file within a watched directory was closed,
              after being opened in writeable mode.  This does not necessarily
              imply the file was written to.

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

       close  A watched file or a file within a watched directory was  closed,
              regardless  of  how  it  was opened.  Note that this is actually
              implemented  simply  by  listening  for  both  close_write   and
              close_nowrite, hence all close events received will be output as
              one of these, not CLOSE.

       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 even if 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 even if 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 is actually implemented simply by  listening  for
              both  moved_to  and  moved_from, hence all close events received
              will be output as one or both of these, not MOVE.

       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  directory  is no longer being watched.  Note that this
              event can occur even if it is not explicitly 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 that this event can occur even if it is not
              explicitly being listened to.

EXAMPLES

   Example 1
       Running inotifywait at the command-line to wait for  any  file  in  the
       ‘test’  directory  to  be  accessed.   After  running inotifywait, ‘cat
       test/foo’ is run in a separate console.

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

   Example 2
       A short shell script to efficiently wait for httpd-related log messages
       and do something appropriate.

       #!/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

   Example 3
       A  custom  output format is used to watch ‘~/test’.  Meanwhile, someone
       runs ‘touch ~/test/badfile; touch ~/test/goodfile;  rm  ~/test/badfile’
       in another console.

       % 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

BUGS

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

       It is assumed the inotify event queue will never overflow.

AUTHORS

       inotifywait   is   written   and   maintained   by    Rohan    McGovern
       <rohan@mcgovern.id.au>.

       inotifywait  is  part  of  inotify-tools.  The inotify-tools website is
       located at: http://inotify-tools.sourceforge.net/

SEE ALSO

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