diff options
Diffstat (limited to 'man/inotifywatch.1')
| -rw-r--r-- | man/inotifywatch.1 | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/man/inotifywatch.1 b/man/inotifywatch.1 new file mode 100644 index 0000000..b8971f6 --- /dev/null +++ b/man/inotifywatch.1 @@ -0,0 +1,271 @@ +.TH inotifywatch 1 "March 14, 2010" "inotifywatch 3.14" + +.SH NAME +inotifywatch \- gather filesystem access statistics using inotify + +.SH SYNOPSIS +.B inotifywatch +.RB [ \-hvzrqf ] +.RB [ \-e +<event> ] +.RB [ \-t +<seconds> ] +.RB [ \-a +<event> ] +.RB [ \-d +<event> ] +<file> [ ... ] + +.SH DESCRIPTION +.B inotifywatch +listens for filesystem events using Linux's +.BR inotify(7) +interface, then outputs a summary count of the events received on each file or +directory. + +.SH OUTPUT +.B 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 +.B \-a +or +.B \-d +options. + +Some diagnostic information will be output on standard error. + +.SH OPTIONS + +.TP +.B \-h, \-\-help +Output some helpful usage information. + +.TP +.B \-v, \-\-verbose +Output some extra information on standard error during execution. +.TP +.B @<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. + +.B Note: +If you need to watch a directory or file whose name starts with @, give the +absolute path. +.TP +.B \-\-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. +.TP +.B \-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 +.I lot +of output! + +.TP +.B \-\-exclude <pattern> +Do not process any events whose filename matches the specified POSIX extended +regular expression, case sensitive. + +.TP +.B \-\-excludei <pattern> +Do not process any events whose filename matches the specified POSIX extended +regular expression, case insensitive. + +.TP +.B \-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. If new directories are created within watched directories they +will automatically be watched. + +.B 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 +.BR /proc/sys/fs/inotify/max_user_watches . + +.TP +.B \-t <seconds>, \-\-timeout <seconds> +Listen only for the specified amount of seconds. If not specified, inotifywatch +will gather statistics until receiving an interrupt signal by (for example) +pressing CONTROL-C at the console. + +.TP +.B \-e <event>, \-\-event <event> +Listen for specific event(s) only. The events which can be listened for are +listed in the +.B EVENTS +section. This option can be specified more than once. If omitted, all events +are listened for. + +.TP +.B \-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 +.B EVENTS +section except `move' and `close' (you must use `moved_to', `moved_from', +`close_write' or `close_nowrite' instead). The default is to sort descending by +`total'. + +.TP +.B \-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 +.B EVENTS +section except `move' and `close' (you must use `moved_to', `moved_from', +`close_write' or `close_nowrite' instead). The default is to sort descending by +`total'. + +.SH "EXIT STATUS" +.TP +.B 0 +The program executed successfully. +.TP +.B 1 +An error occurred in execution of the program. + +.SH EVENTS +The following events are valid for use with the +.B \-e +option: + +.TP +.B access +A watched file or a file within a watched directory was read from. + +.TP +.B modify +A watched file or a file within a watched directory was written to. + +.TP +.B attrib +The metadata of a watched file or a file within a watched directory was +modified. This includes timestamps, file permissions, extended attributes etc. + +.TP +.B 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. + +.TP +.B close_nowrite +A watched file or a file within a watched directory was closed, after being +opened in read-only mode. + +.TP +.B 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 +.B close_write +and +.B close_nowrite, +hence all close events received will be output as one of these, not +.B CLOSE. + +.TP +.B open +A watched file or a file within a watched directory was opened. + +.TP +.B 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. + +.TP +.B 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. + +.TP +.B move +A file or directory was moved from or to a watched directory. Note that this is +actually implemented simply by listening for both +.B moved_to +and +.B moved_from, +hence all close events received will be output as one or both of these, not +.B MOVE. + +.TP +.B move_self +A watched file or directory was moved. After this event, the file or directory +is no longer being watched. + +.TP +.B create +A file or directory was created within a watched directory. + +.TP +.B delete +A file or directory within a watched directory was deleted. + +.TP +.B 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. + +.TP +.B 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. + + +.SH EXAMPLE + +Watching the `~/.beagle' directory for 60 seconds: + +.nf +% 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/ +.fi + +.SH 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. + +.SH AUTHORS +inotifywatch is written by Rohan McGovern <rohan@mcgovern.id.au>. + +inotifywatch is part of inotify-tools. The inotify-tools website is located at: +.I http://inotify-tools.sourceforge.net/ + +.SH "SEE ALSO" +inotifywait(1), inotify(7) |