Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
inotifywait(1)		    General Commands Manual		inotifywait(1)

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  ino-
       tify(7)	interface.   It	 is  suitable for waiting for changes to files
       from shell scripts.  It can either exit once an event occurs,  or  con-
       tinually	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  config-
       ured, 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 op-
	      tions will be helpful in this case.

OPTIONS
       -h, --help
	      Output some helpful usage	information.

       @<file>
	      When watching a directory	tree recursively, exclude  the	speci-
	      fied file	from being watched.  The file must be specified	with a
	      relative or absolute path	according to whether a relative	or ab-
	      solute  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  in-
	      put.   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  in-
	      definitely.   The	 default  behaviour is to exit after the first
	      event occurs.

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

       -o, --outfile <file>
	      Output events to <file> rather than stdout.

       -s, --syslog
	      Output errors to syslog(3) system	log module rather than stderr.

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

	      Warning: If you use this option while watching the  root	direc-
	      tory  of	a large	tree, it may take quite	a while	until all ino-
	      tify 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 ino-
	      tify  watches  per user will be reached.	The default maximum is
	      8192; it	can  be	 increased  by	writing	 to  /proc/sys/fs/ino-
	      tify/max_user_watches.

       -q, --quiet
	      If  specified  once, the program will be less verbose.  Specifi-
	      cally, it	will not state when it has completed establishing  all
	      inotify watches.

	      If  specified twice, the program will output nothing at all, ex-
	      cept 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>
	      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 lis-
	      tened  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.  Oth-
	      erwise, 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	which-
	      ever 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  oc-
	      curred  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	speci-
	      fied 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	direc-
	      tory 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 im-
	      plemented	 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.

       move_self
	      A	 watched  file	or  directory was moved. After this event, the
	      file or directory	is 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	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 imme-
       diately 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@mcgov-
       ern.id.au>.

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

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

inotifywait 3.14		April 29, 2017			inotifywait(1)

NAME | SYNOPSIS | DESCRIPTION | OUTPUT | OPTIONS | EXIT STATUS | EVENTS | EXAMPLES | BUGS | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=inotifywait&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help