\input texinfo @c -*-texinfo-*-
@c This file uses the @command command introduced in Texinfo 4.0.
@c %**start of header
@setfilename fileschanged.info
@settitle display altered files
@finalout
@setchapternewpage odd
@c %**end of header

@include package.texinfo


@ifinfo
This file documents the @command{fileschanged} command which displays altered files

Copyright (C) 2002 @value{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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
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.
@end ifinfo

@titlepage
@title fileschanged
@subtitle displays altered files
@subtitle for fileschanged Version @value{VERSION}
@author by @value{MAINTAINER}

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2002 @value{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.
@end titlepage

@c All the nodes can be updated using the EMACS command
@c texinfo-every-node-update, which is normally bound to C-c C-u C-e.
@node Top, Instructions, (dir), (dir)

@ifinfo
This file documents the @command{fileschanged} command to display altered files.
@end ifinfo

@c All the menus can be updated with the EMACS command
@c texinfo-all-menus-update, which is normally bound to C-c C-u C-a.
@menu
* Instructions::                About this manual. 
* Copying::                     How you can copy and share @command{fileschanged}.
* Overview::                    Preliminary information.
* Sample::                      Sample output from @command{fileschanged}.
* Invoking fileschanged::       How to run @command{fileschanged}.
* Problems::                    Reporting bugs.
* Concept Index::               Index of concepts.
@end menu

@node Instructions, Copying, Top, Top
@chapter How to Read This Manual

@cindex reading
@cindex manual, about this manual
@cindex about 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 @value{MAINTAINER}.  What you are reading now is the authoritative documentation for the @command{fileschanged} program.  The man pages will be maintained but will not be as valuable of a resource as this document is.  

@node Copying, Overview, Instructions, Top
@include gpl.texinfo

@node Overview, Sample, Copying, Top
@chapter Overview
@cindex greetings
@cindex overview

The @command{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 @command{fileschanged} in shell scripts to take action when monitored files become altered.  In it's simplest form, you can give @command{fileschanged} filenames to monitor from stdin, and it will report when those files have changed via stdout.  You can stop @command{fileschanged} from monitoring files by pressing CTRL-C.  In a more complex usage, @command{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 @command{fileschanged} was written by @value{MAINTAINER}.

@node Sample, Invoking fileschanged, Overview, Top
@chapter Sample Output
@cindex sample

Here are some realistic examples of running @command{fileschanged}.

Try the command @samp{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.

@example
/home/ben/.xsession-errors
/home/ben/mbox
@end example

In this example, two files were altered in my (Ben's) home directory 
after the @command{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.  @command{fileschanged} will continue to run until you 
interrupt it by pressing CTRL-C.


@node Invoking fileschanged, Problems, Sample, Top
@chapter Invoking @command{fileschanged}
@cindex invoking
@cindex version
@cindex options
@cindex usage
@cindex help
@cindex getting help

This is the output of the command @samp{fileschanged --help}:

@noindent
@verbatiminclude usage
@verbatim

@end verbatim

@code{fileschanged} supports the following options:

@c Formatting copied from the Texinfo 4.0 manual.
@table @code
@item -p
@itemx --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).

@item -s
@itemx --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.

@item -c
@itemx --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 @command{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.

@item -C
@itemx --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.

@item -d
@itemx --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.

@item -e
@itemx --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.

@item -E
@itemx --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.

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

@item -l
@itemx --filelist=FILE
Monitor the list of filenames in FILE.
FILE contains a list of absolutely or relatively specified filenames that @command{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 @command{fileschanged} as it's own script.
For example you can make a script that looks like:

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

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

@item -r
@itemx --recursive
Monitor subdirectories of directories.
Monitor files within subdirectories within monitored directories.

@item -t seconds
@itemx --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 @command{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.

@item -a
@itemx --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.

@item -x PROG
@itemx --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.

@item -L
@itemx --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.

@end table

@node Problems, Concept Index, Invoking fileschanged, Top
@chapter Reporting Bugs
@cindex bugs
@cindex problems

If you find a bug in @command{fileschanged}, please send electronic mail to
@email{@value{ADDRESS}}.  Include the version number, which you can find by
running @w{@samp{fileschanged --version}}.  Also include in your message the
output that the program produced and the output you expected.@refill

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

@node Concept Index,  , Problems, Top
@unnumbered Concept Index

@shortcontents
@contents
@bye
