gbch-filemon - monitor for changes to files

# NAME

gbch-filemon - monitor for changes to files

# SYNOPSIS

gbch-filemon [ -options ]

gbch-xfilemon

# DESCRIPTION

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.

# OPTIONS

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

-? or +explain

  causes a summary of the other options to be displayed without taking further action.

-A or +file-arrives

  Perform the required action when a new file is detected in the directory.

-a or +any-file

  Perform the required action for any file name.

-C or +continue-running

  Continue gbch-filemon after a matching file and condition has been found, looking for further files.

-c command

  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'"

-D dir or +directory dir

  Specify the given dir as the directory to monitor rather than the current directory.

-d or +daemon-process

  Detach a futher gbch-filemon as a daemon process, and return to the user.

-e or +include-existing

  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.

-G secs or +file-stops-growing secs

  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.

-I secs or +file-stops-changing secs

  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.

-i or +ignore-existing

  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.

-K or +kill-all

  Kill all gbch-filemon daemon processes belonging to the user, or all processes if invoked by `root`.

-k dir or +kill-processes dir

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

-L or +follow-links

  Follow symbolic links to files (and subdirectories with the -R option).

-l or +list-processes

  List running gbch-filemon processes and which directories they are accessing.

-M secs or +file-stops-writing secs

  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.

-m or +run-monitor

  Run as a file monitor program (default) rather than -l, -k or -K.

-n or +not-daemon

  Do not detach gbch-filemon as a daemon process (default), wait and only return to the user when a file event has been detected.

-P secs or +poll-time secs

  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.

-p pattern or +pattern-file pattern

  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.

-R or +recursive

  Recursively follow subdirectories of the starting directory.

-r or +file-deleted

  Perform action when a file matching the criteria has been deleted.

-S or +halt-when-found

  Halt gbch-filemon once a matching file and condition has been found.

-s file or +specific-file file

  Perform action only with a specific named file, not a pattern.

-u secs or +file-stops-use secs

  Perform action when a file has appeared, and has not been read for at least secs.

-X script

  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:

  1. File name

  2. Directory path

  3. File size (or last file size if file deleted).

  4. Date of file modification, change or access as YYYY/MM/DD, but only for those type of changes.

  5. Time of file modification, change or access as HH:MM:SS, but only for those type of changes.

+freeze-current

  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.

+freeze-home

  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.

## File matching

What to look for may be made to depend upon something happening to

Any file

  With the -a option. Any file that meets the other criteria will trigger the event.

Specific file

  With the -s option, gbch-filemon will watch for the specific file named.

Pattern

  With the -p option, a file which matches the pattern and the other criteria will trigger the action.

## Criteria

There are 6 criteria to watch for.

File arriving

  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.

File removal

  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.

File stopped growing

  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.

File no longer written

  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.

File no longer changed

  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.

File no longer used

  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.

## Pre-existing files

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.

## Recursive searches

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.

# EXAMPLES

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"

# FILES

~/.gnubatch configuration file (home directory)

.gnubatch configuration file (current directory)

filemon.help message file

# ENVIRONMENT

GBCH_FILEMON

  space-separated options to override defaults.

FILEMONCONF

  location of alternative help file.

# DIAGNOSTICS

Various diagnostics are read and printed as required from the message file filemon.help.

# COPYRIGHT

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.

# AUTHOR

John M Collins, Xi Software Ltd.