     [file package.texinfo not included]

This file documents the fileschanged command which displays altered files

Copyright (C) 2002 MAINTAINER

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

This file documents the fileschanged command to display altered files.

How to Read This Manual
***********************

This manual is incomplete: No attempt is made to explain basic file concepts in a way suitable for novices.  Thus, if you are interested, please get involved in improving this manual.  The entire free software community will benefit.

This manual was originally derived from the Unix man pages in the distribution, which were written by MAINTAINER.  What you are reading now is the authoritative documentation for the fileschanged program.  The man pages will be maintained but will not be as valuable of a resource as this document is.

     [file gpl.texinfo not included]

Overview
********

The fileschanged utility is a FAM (File Alteration Monitor) client.  From the command-line it monitors sets of files and shows you when they change.  You can use fileschanged in shell scripts to take action when monitored files become altered.  In it's simplest form, you can give fileschanged filenames to monitor from stdin, and it will report when those files have changed via stdout.  You can stop fileschanged from monitoring files by pressing CTRL-C.  In a more complex usage, fileschanged can monitor command-line specified files recursively, while following symbolic links, while staying on the current filesystem, and reporting deleted files as well as created and changed files that haven't been written to for 2 seconds.  This software is protected by the GNU General Public License, so users are free to share and change it.

GNU fileschanged was written by MAINTAINER.

Sample Output
*************

Here are some realistic examples of running fileschanged.

Try the command fileschanged -r ~/ . Using this command you can monitor all of the files in your home directory and below. The -r means to monitor subdirectories of any specified directories.

     /home/ben/.xsession-errors
     /home/ben/mbox

In this example, two files were altered in my (Ben's) home directory after the fileschanged command was executed.  When my mbox file changes, I know I have mail.  When my .xsession-file changes I know that something has gone wrong with X, or there are some warnings that I want to know about.  fileschanged will continue to run until you interrupt it by pressing CTRL-C.

Invoking fileschanged
*********************

This is the output of the command fileschanged --help:

     [file usage not included]

fileschanged supports the following options:

-p
--display-action
     Report action when reporting altered files.  Instead of reporting just the filename, this option forces fileschanged to state the action before the filename.  The following is a list of actions that fileschanged can state: created (A), changed (M), deleted (R), started-executing (E), finished-executing (X).

-s
--show=EVENT
     Show filenames when an EVENT happens.  Events are: created, changed, deleted, executing, executed, and all.  created and changed events are turned on by default if no other events are specified.

-c
--show-created
     Show newly created files.  This option is turned on by default. If you are monitoring a directory, and a new file is created inside that directory then this option will ensure that any new files are reported. If a new sub-directory is created inside of a directory that fileschanged is monitoring, it will not be monitored unless you've specified the -r (--recursive) option on the command-line. If this option is used in conjunction with the -C (--show-changed) option then reporting will be delayed until no further writes have been detected. The number of seconds in this delay is specified in the -t (--timeout) option. This option is deprecated.  Same as --show=created.

-C
--show-changed
     Show modified files.  This option is turned on by default. When a file you are monitoring is modified, it will be reported as being changed. The reporting will be delayed until no further writes have been detected. Directory files cannot be monitored with fileschanged. This option is deprecated.  Same as --show=changed.

-d
--show-deleted
     Show deleted files. When a monitored file is deleted or moved it will be reported immediately. This option is deprecated.  Same as --show=deleted.

-e
--show-executing
     Show executing files. When a monitored file is first executed it will be reported immediately. This option is deprecated.  Same as --show=executing.

-E
--show-executed
     Show executed files. When a monitored file stops it's execution it will be reported immediately. This option is deprecated.  Same as --show=executed.

-f
--files-to-monitor
     Monitor the list of files specified on the command line. This option is the default way to specify filenames. fileschanged needs to know what files to monitor for alterations. All files that you specify must exist when fileschanged begins execution or they will not be monitored.

-l
--filelist=FILE
     Monitor the list of filenames in FILE. FILE contains a list of absolutely or relatively specified filenames that fileschanged is to monitor. Using this option you can do some interesting things.

     i. you can pipe the find command through fileschanged. ii. you can use fileschanged as it's own script. For example you can make a script that looks like:

          #!/usr/bin/fileschanged -l
          ~/mbox
          .xsession-errors

     All files that you specify must exist when fileschanged begins execution or they will not be monitored.

-r
--recursive
     Monitor subdirectories of directories. Monitor files within subdirectories within monitored directories.

-t seconds
--timeout=seconds
     Assume changed after N secs of no writes. (Def=2). When a monitored and modified file hasn't been written to for 2 seconds, then report it as changed. The idea here is to detect when a file is finished being written to (eg. finished changing on disk). If you specify this value as 0 then fileschanged will report that the file has been modified upon every disk write. Note: The default 2 seconds is too small for large files, but works well with small files. This option is used in conjunction with the -C (--show-changed) option.

-a
--show-all
     Same as --show=all -p Show when files have been created, changed, deleted, executed, or if a file has finished executing.  Along with the filename, show the kind of event.

-x PROG
--exec=PROG
     Run PROG when file is altered (PROG action filename). Will execute `PROG' with the action and filename as parameters whenever that event occurs. Action is one of A, M, R, E or X. Filename is an absolutely specified path to the file.

-L
--dereference
     Don't monitor symlinks, monitor what's pointed to. Use this option to monitor the files that symbolic links point to, instead of monitoring the symlink itself.

Reporting Bugs
**************

If you find a bug in fileschanged, please send electronic mail to ADDRESS.  Include the version number, which you can find by running fileschanged --version.  Also include in your message the output that the program produced and the output you expected.

If you have other questions, comments or suggestions about fileschanged, contact the author via electronic mail to ADDRESS.  The author will try to help you out, although he may not have time to fix your problems.

Concept Index
*************