Watch: Directory Tree and File Event Watcher


Watch is shell utility that allows one to track directory and file state changes. It is similar to FAM [] and dnotify [] , but is implemented directly on top of the *BSD kqueue interface specification.

Sample shell-scripts will be provided to demonstrate how to use Watch within Unix pipe-lines. Watch can read directives on stdin and output state changes on stdout.

A sister project [libkqueue.html] is developing a portable, user-land kqueue library, utilizing what edge and level-triggered event system is available (e.g. epoll() and DNOTIFY for socket and directory events, respectively, on Linux; and possibly /dev/poll and sleep()+stat() for Solaris; and select()/poll() and sleep()+stat() for other platforms).



Fixed an elusive segfault bug in a string format specifier (forgot to pass the arguments, d'oh!). I've been stress testing it with rapid operations on large trees. Sending SIGUSR1 to a running process will dump the internal structures. It seems that even though files are updated properly internally, some are not being reported. Back to work....


Added -W switch. -w will coalesce a fixed amount of time, then output the events. -W is the extended version, which will wait the specified amount of time from the last event. If a file is being continuously updated it will not be reported until there is no activity for the specified amount of time. Deletions are reported immediately. A delete followed by a creation of a specific path are not coalesced.


forget() has been fleshed out in the code, so that proper forgetting occurs. However, this is a one time directive if recursion is specified; there is no memory of forgotten files/directories so it's possible that they could be picked up again (as additions) after a deletion or creation event occurs.

There is a bug where file tracking will turn directory recursion on (not explicitly, but in the process of walking a dir to watch the files, directories are descended into unintentionally).


After having learned that the NOTE_MODIFY filter flag in kqueue does not notify of file modifications within a directory (to get modifications one must hold and enqueue an open descriptor), I've had to re-tool a bit, which kind of got ugly. But, now most of the functionality should be there, with the exception of explicit removal directives (only physically removed file and directories are forgotten, otherwise reporting cannot be turned off).

Since kqueue cannot notify on a file modification within a directory, I've added a check in the code for NOTE_DMODIFY. If this is present then each and every file will not need to be opened, using up valuable, finite descriptor table space. Linux's DNOTIFY mechanism will allow this capability to be built into the portable libkqueue.


Copyright (C) 2003 William Ahern [] .

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. []


			Usage: watch [options] [[file/dir] [...]]
			  -d CH directory/file delimiter (default: '\n')
			  -r    recurse into directories
			  -f    notify about specific file changes in directories
			  -i FN include shell globbing pattern
			  -x FN exclude shell globbing pattern
			  -I RE include posix regular expression pattern
			  -X RE exclude posix regular expression pattern
			  -m  # set descriptor limit (max open files)
			  -M    set descriptor limit to maximum allowable
			  -w  # wait # seconds to coalesce events
			  -W  # wait # seconds from last event to coalesce
			  -v    display version information and exit
			  -h    display this help and exit


Source-code is available by anonymous CVS. You can view and download a tarball of the source over the web [] , or you can checkout the tree from the command-line like so:

cvs -z9 -d checkout watch

A sample Makefile to drop in src/ until autoconf/automake is configured properly:

				gcc -g -Wall -pipe -DHAVE_SYS_EVENT_H -o watch *.c

				rm watch *~


There are no installable packages yet.


If you find this work useful, show your gratitude by giving back to the community [] .

other projects

airctl | bsdauth | cnippets | libkqueue | watch | AnonNet