dnotify
=======

dnotify is a simple program that makes it possible to execute a command
every time the contents of a specific directory change in linux. It is run
from the command line and takes two arguments: one or more directories to
monitor and a command to execute whenever a directory has changed. Options
control what events to trigger on: when a file was read in the directory,
when one was created, deleted and so on.

dnotify is written entirely in C, and uses the linux kernel directory
notification feature to monitor directories. Because of this,
dnotify does not need to poll files every few seconds (like `tail -f'
does). All time is spent sleeping until an event occurs. This also means
that dnotify only works with recent versions linux (2.4.19 or later is
required).

NOTE: Due to limitations in the kernel interface which dnotify uses, it is
not possible to see the name of the file changed in the monitored
directory. There is another project that implements this functionality
though through a kernel patch. The patch and user space program is written
by Rüdiger Klaehn and can be downloaded from
http://www.lambda-computing.com/~rudi/dnotify/.

Copyright and License
=====================

dnotify is copyright (C) 2002 Oskar Liljeblad.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Requirements
============

The following programs are required to build dnotify:

* gcc 2.95 or later.

  The dnotify program uses some features specific to gcc 2.95
  (such as macros with variable number of arguments). Naturally,
  gcc 3.0 and later will do just as good.

* GNU libc6 2.2 or later, but not GNU libc6 2.3.1.

  Version 2.2 of the libc contains the necessary headers for the
  directory notification facilities in the kernel.

  There is a bug in GNU libc 2.3.1 which misdefines SIGRTMIN to -1
  instead of its normal value, 32. This means you cannot compile
  dnotify with this version of GNU libc. The bug was fixed in
  libc6 2.3.1-4 in Debian and in the GNU libc6 CVS on 2002-10-29.

The following programs are required for proper operation of dnotify:

* GNU libc6 2.2 or later, but not GNU libc6 2.3.1.

  The dnotify program uses GNU-specific extensions to the C library
  (getopt_long, program_invocation_name etc).

* Linux kernel 2.4.19 or later

  Support for dnotify facilities were added to the kernel as of 2.1.70.
  However, there was a serious bug that prevented dnotify from working
  properly that was not fixed until in 2.4.19. The fix should be included
  in 2.4.19pre2aa2 and later.
  
Building and Installation
=========================

Compile dnotify by running `configure' and then `make'. This should produce
an executable `dnotify', which can be used right away.

The configure script will check for the existence of the `fl_owner' bug
mentioned above unless `--disable-flowner-check' is given as an option.
This can be used when building dnotify on earlier kernels (however
dnotify will still only run correctly if you have 2.4.19 or later).

The configure script will also check for support for real-time signals
in the C library and the kernel. This check can be disabled with
`--disable-sigrtmin-check', but this is not recommended since the
compilation might fail ("SIGRTMIN not defined").

If you want to install the dnotify on your system, run `make install'. This
will copy the executable and the man page into the appropriate directories
(/usr/local/bin and /usr/local/share/man/man1 by default).

For further details regarding `configure' and `make', see the INSTALL
document.

Usage
=====

The dnotify program supports the usual `--help' option which displays usage
and option information. The supplied manual page can be viewed with

  man ./dnotify.1

Homepage
========

The latest version of dnotify can be downloaded from

  http://www.student.lu.se/~nbi98oli/dnotify.html

Feedback
========

The author of dnotify and this document, Oskar Liljeblad, can be reached
via email:

  oskar@osk.mine.nu
  
Please send bug reports, suggestions, ideas or comments in general to me.

Known bugs
==========

`{}' in the command specification cannot be escaped.

Due to limitations of the kernel interface which dnotify uses,
it is not possible to see the name of the file changed in the monitored
directory.

dnotify will only scan directories once to find out subdirectories to monitor
when recursive mode is enabled. If you want to monitor any subdirectory
created, you will have to stop and restart dnotify every time a create or delete
event occurs.

Possible things to do
=====================

Please see the TODO file.

Similar projects
================

changedfiles
http://freshmeat.net/projects/changedfiles/

  This program uses a kernel module which makes it possible to monitor
  file changes as well it seems. A daemon running in user space
  is used to react on the changes.

FAM
http://freshmeat.net/projects/fam/

  Like changedfiles this project also uses a daemon. The difference
  is that no kernel module is used.

Enhanced file change notification for linux
http://www.lambda-computing.com/~rudi/dnotify/

  This project provides recursive directory notification and passes
  the name of the file changed to user space. A kernel modification
  is necessary however.

-