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

FreeBSD Manual Pages

  
 
  

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

NAME
       inotifywatch - gather filesystem	access statistics using	inotify

SYNOPSIS
       inotifywatch  [-hvzrqf] [-e <event> ] [-t <seconds> ] [-a <event> ] [-d
       <event> ] <file>	[ ... ]

DESCRIPTION
       inotifywatch listens for	filesystem events using	Linux's	inotify(7) in-
       terface,	 then  outputs	a summary count	of the events received on each
       file or directory.

OUTPUT
       inotifywatch will output	a table	on standard out	with  one  column  for
       each type of event and one row for each watched file or directory.  The
       table will show the amount  of  times  each  event  occurred  for  each
       watched	file or	directory.  Output can be sorted by a particular event
       using the -a or -d options.

       Some diagnostic information will	be output on standard error.

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

       -v, --verbose
	      Output some extra	information on standard	 error	during	execu-
	      tion.

       @<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.

       -z, --zero
	      Output table rows	and columns even if all	elements are zero.  By
	      default, rows and	columns	are only output	if they	 contain  non-
	      zero  elements.  Using this option when watching for every event
	      on a lot of files	can result in a	lot of output!

       --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.

       -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.  If new directories  are  created
	      within watched directories they will automatically 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.

       -t <seconds>, --timeout <seconds>
	      Listen only for the specified amount of seconds.	If not	speci-
	      fied, inotifywatch will gather statistics	until receiving	an in-
	      terrupt signal by	(for example) pressing CONTROL-C at  the  con-
	      sole.

       -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.

       -a <event>, --ascending <event>
	      Sort output ascending by event counts for	the  specified	event.
	      Sortable events include `total' and all the events listed	in the
	      EVENTS  section  except  `move'  and  `close'  (you   must   use
	      `moved_to',  `moved_from',  `close_write'	or `close_nowrite' in-
	      stead).  The default is to sort descending by `total'.

       -d <event>, --descending	<event>
	      Sort output descending by	event counts for the specified	event.
	      Sortable events include `total' and all the events listed	in the
	      EVENTS  section  except  `move'  and  `close'  (you   must   use
	      `moved_to',  `moved_from',  `close_write'	or `close_nowrite' in-
	      stead).  The default is to sort descending by `total'.

EXIT STATUS
       0      The program executed successfully.

       1      An error occurred	in execution of	the program.

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.

EXAMPLE
       Watching	the `~/.beagle'	directory for 60 seconds:

       % inotifywatch -v -e access -e modify -t	60 -r ~/.beagle
       Establishing watches...
       Setting up watch(es) on /home/rohan/.beagle
       OK, /home/rohan/.beagle is now being watched.
       Total of	302 watches.
       Finished	establishing watches, now collecting statistics.
       Will listen for events for 60 seconds.
       total  access  modify  filename
       1436   1074    362     /home/rohan/.beagle/Indexes/FileSystemIndex/PrimaryIndex/
       1323   1053    270     /home/rohan/.beagle/Indexes/FileSystemIndex/SecondaryIndex/
       303    116     187     /home/rohan/.beagle/Indexes/KMailIndex/PrimaryIndex/
       261    74      187     /home/rohan/.beagle/TextCache/
       206    0	      206     /home/rohan/.beagle/Log/
       42     0	      42      /home/rohan/.beagle/Indexes/FileSystemIndex/Locks/
       18     6	      12      /home/rohan/.beagle/Indexes/FileSystemIndex/
       12     0	      12      /home/rohan/.beagle/Indexes/KMailIndex/Locks/
       3      0	      3	      /home/rohan/.beagle/TextCache/54/
       3      0	      3	      /home/rohan/.beagle/TextCache/bc/
       3      0	      3	      /home/rohan/.beagle/TextCache/20/
       3      0	      3	      /home/rohan/.beagle/TextCache/62/
       2      2	      0	      /home/rohan/.beagle/Indexes/KMailIndex/SecondaryIndex/

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
       inotifywatch is written by Rohan	McGovern <rohan@mcgovern.id.au>.

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

SEE ALSO
       inotifywait(1), inotify(7)

inotifywatch 3.14		April 29, 2017		       inotifywatch(1)

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

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

home | help