gbch-filemon - monitor for changes to files
gbch-filemon [ -options ]
gbch-filemon executes a given program or script when specified files change in specified ways in a specified directory.
It is intentionally not integrated with the GNUbatch core product, as there is no automatic mechanism within Unix for signalling changes to files, and it is therefore necessary to ``poll'' or monitor the files aaat a given interval. gbch-filemon is made as small as possible so that the ``polling'' does not have a large impact on the system.
The rest of GNUbatch is made to be ``event-driven'', as this has minimal impact on the system when the product is inactive.
The ``action'' of gbch-filemon may be to run a GNUbatch job, set a variable, or perform some completely unrelated task.
Gbch-filemon may optionally be used to list or terminate running copies of itself.
The GTK program gbch-xfilemon(1) or the X/Motif program gbch-xmfilemon(1) may be used to set up the options to and run gbch-filemon rather than remembering them here.
Note that the order of treatment, letters and keywords described below may be modified by editing the file filemon.help - see btsyntax(5).
The environment variable on which options are supplied is GBCH_FILEMON
and the environment variable to specify the help file is FILEMONCONF
.
causes a summary of the other options to be displayed without taking further action.
Perform the required action when a new file is detected in the directory.
Perform the required action for any file name.
Continue gbch-filemon after a matching file and condition has been found, looking for further files.
Specify command to execute when one of the monitored events occurs. This is an alternative to -X, which runs a named shell script.
In the command the sequence %f is replaced by the name of the file whose activity has provoked the action, and %d by the directory.
To use this option, be sure to enclose the whole shell command in quotes so that it is passed as one argument, thus:
-c "xmessage -bg red 'Found %f'"
Specify the given dir as the directory to monitor rather than the current directory.
Detach a futher gbch-filemon as a daemon process, and return to the user.
Include existing files in the scan, and report changes etc to those. If the -A option (watch for file arriving), this will have no effect unless an existing file is deleted and is recreated.
Activate command when a file has appeared, and has not grown further for at least secs. Distinguish this from the -M option, which will check for any change, possibly in the middle of a file.
Activate command when a file has appeared, and has not been changed for at least secs. This is more inclusive than -M, as it includes activities such as changing the ownership or mode of the file, or making hard links.
Ignore existing files (default). However if an existing file is noted to have been deleted, and then re-created, the new version will be treated as a new file.
Kill all gbch-filemon daemon processes belonging to the user, or all
processes if invoked by root
.
Kill any gbch-filemon daemon processes left running which are scanning
the given directory. Processes must belong to the invoking user, or
gbch-filemon be invoked by root
.
Follow symbolic links to files (and subdirectories with the -R option).
List running gbch-filemon processes and which directories they are accessing.
Activate command when a file has appeared, and has not been written to for at least secs. This is more inclusive than B-G>, as it includes writes other than to the end of the file. It is less inclusive than -I, which also monitors for linking and permission-changing.
Run as a file monitor program (default) rather than -l, -k or -K.
Do not detach gbch-filemon as a daemon process (default), wait and only return to the user when a file event has been detected.
Poll directory every secs seconds. This should be sufficiently small not to ``miss'' events for a long time, but large enough to not load the system. The default if this is not specified is 20 seconds.
Perform action on a file name matching pattern.
Pattern may take the form of wild-card matching given by the shell,
with *
, ?
, [a-z]
, [!a-z]
having the same meanings as with
the shell, and possible alternative patterns separated by commas, for
example:
-p '*.[chyl],*.obj'
Remember to enclose the argument in quotes so that it is interpreted by gbch-filemon and not the shell.
Recursively follow subdirectories of the starting directory.
Perform action when a file matching the criteria has been deleted.
Halt gbch-filemon once a matching file and condition has been found.
Perform action only with a specific named file, not a pattern.
Perform action when a file has appeared, and has not been read for at least secs.
Specify the given script as a shell script to execute when one of the monitored events occurs. This is an alternative to -c. The existence of the shell script is checked, and gbch-filemon will fail with an error message if it does not exist.
The shell script is passed the following arguments:
File name
Directory path
File size (or last file size if file deleted).
Date of file modification, change or access as YYYY/MM/DD, but only for those type of changes.
Time of file modification, change or access as HH:MM:SS, but only for those type of changes.
Save all the current options in a .gnubatch file in the current
directory with keyword BTFILEMON
. If this is specified,
gbch-filemon will terminate after saving the file.
Save all the current options in a .gnubatch file in the user's home directory. If this is specified, gbch-filemon will terminate after saving the file.
What to look for may be made to depend upon something happening to
With the -a option. Any file that meets the other criteria will trigger the event.
With the -s option, gbch-filemon will watch for the specific file named.
With the -p option, a file which matches the pattern and the other criteria will trigger the action.
There are 6 criteria to watch for.
This is probably the most common case. If you want to wait for a file being written and trigger an event, the -A option will look for this.
This will watch for files being deleted, for example some applications use a ``lock file'' to denote that they are being run, and you might wish to start something else when it has gone.
Remember that you might want to include existing files in the scan with -e if the file in question existed when you started gbch-filemon.
What this watches for is for a file being having been created, or with the -e option starting to ``grow'', and then apparently no longer grown for the given time.
If files are arriving from FTP, for example, then when they are complete, they will cease to ``grow'' in size.
A file not used sequentially may be written to internally rather than have additional data appended. This often occurs with database files, where records are updated somewhere in the middle of the file. If a series of database transactions is made and then completed, the file will no longer be written to for some time, and gbch-filemon can be made to trigger an action after that time.
You will often want to include the -e option if the file existed already on entry.
This goes a stage further than ``no longer written'' as it includes any kind of change to the file, such as permissions, owner, hard links or change of access and write times.
This monitors the access time of the file, updated whenever the file is read, and proceeds when this has gone unchanged for the specified time.
You will often want to include the -e option with this if the file existed already on entry.
If the -i (ignore existing) option is specified, which is the default, then no changes to existing files which would otherwise match the criteria will be considered, except where an existing file is deleted and then recreated and gbch-filemon ``notices'' this happen, in that the file is deleted before one ``poll'' of the directory and recreated before another. In other words, if the poll time is 20 seconds, then the deletion and recreation will have to be 20 seconds apart.
If the -e option to include existing files is specified, the -G, -u, -M, -I and -r options will work as for new files but not -A, as the file has already ``arrived''. However, if it is deleted, this is ``noticed'' and then recreated, it will be treated as a ``new'' file.
If recursive searches are specified using the -R option, a separate gbch-filemon process will be invoked for each subdirectory, for each further subdirectory within each of those subdirectories, and for each new subdirectory created within one of those whilst each process is running, unless the -r option is being used to watch for file removal, whereupon only those subdirectories which existed to begin with will be considered.
If the -S option is specified to stop once a file has been found, each process will continue until a file is found in its particular subdirectory.
Monitor the FTP directories for new files which have finished arriving, sending a message to the user:
gbch-filemon -aRC -D /var/spool/ftp -G 30 -c "xmessage '%f in %d'"
Set a GNUbatch variable to an appropriate value when a file arrives in the current directory
gbch-filemon -aAC -c "gbch-var -s '%f arrived' file_var"
~/.gnubatch configuration file (home directory)
.gnubatch configuration file (current directory)
filemon.help message file
space-separated options to override defaults.
location of alternative help file.
Various diagnostics are read and printed as required from the message file filemon.help.
Copyright (c) 2009 Free Software Foundation, Inc. This is free software. You may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.
John M Collins, Xi Software Ltd.