direvent - directory event monitor
] [-F NAME
] [-P FILE
[ -l PRIO
] [-I DIR
] [-T COMMAND
monitors a set of directories on the file system and reacts
when a file system event occurs in any of them. Directories and events to
monitor are specified in the configuration file. When an event occurs the
utility reacts by invoking an external command configured for that event.
The following generic
events can be monitored by the program:
- A file was created;
- A file was deleted;
- A file was written to;
- File attributes have changed. This includes changes in the
file ownership, mode, link count, etc.
Depending on the interface provided by the underlying operating system
can trace various system-dependent
events, which may
offer a better resolution. These events are described in the section SYSTEM
is a configuration entity within direvent
associates a set of directories with a set of events and instructs the program
to run a specified external command when any of these events occur in any of
these directories. This external command (called a handler
) can obtain
information about the event that triggered its execution from the environment
variables, or from its command line (see the HANDLER ENVIRONMENT
Watchers are declared in the program configuration file direvent.conf
located in the system configuration directory (normally /etc
An alternative configuration file can be used, by supplying its pathname as the
command line argument ( CONFIG
parameter in the SYNOPSIS
- -d, --debug
- Increase debug verbosity level.
- -F, --facility=FACILITY
- Log under this syslog facility. Allowed values for
FACILITY are a decimal number or any of the following symbolic
names: auth, authpriv, cron, daemon,
ftp, local0 through local7, lpr, mail,
news, user, and uucp.
The option -F 0 directs logging to the standard error.
- -f, --foreground
- Run in the foreground.
- -I, --include=DIR
- Add DIR to the include search path. When looking for
a file to be included in the #include (#include_once)
statement, direvent scans first the directories given with
-I options (in the same order as given on the command line), and
then the directories in the standard include search path. The latter is
defined at compile time and can be inspected in the output of the
- -l PRIO
- While connected to a terminal direvent outputs its
diagnostics messages to stderr and, if configured, to syslog. This
option limits the amount of information output to the standard error.
PRIO is one of the following priorities (in order of increasing
severity): debug, info, notice, warning,
err, crit, alert, emerg. When this option is
given, only messages with the priority level equal to or greater than
PRIO will be duplicated on the standard error.
- -P, --pidfile=FILE
- Write PID to FILE.
- -T, --self-test=COMMAND
- Run in self-test mode. In this mode, direvent
starts external command supplied as the argument to this option and
continues running until the command exits. If the command terminates
normally, direvent exits with the code returned by it. If the
command terminates on SIGHUP, direvent exits with code 0. If
it terminates on another signal, direvent exits with code 2.
COMMAND can include any command line options or arguments, provided
that it is properly quoted. It is invoked as /bin/sh -c
COMMAND in the environment of the parent direvent
The macro variable $self_test_pid holds the PID of the COMMAND
(see section MACRO EXPANSION in direvent.conf(5)).
- -t, --lint
- Check configuration file for errors and exit.
- -u, --user=USER
- Run as this USER.
Informative options cause the program to display the requested piece of
information and exit:
- -h, --help
- Output a terse help summary and exit.
- -H, --config-help
- Describe configuration file syntax.
- Show available command line options.
- -V, --version
- Print program version and copyright information.
The default configuration file is /etc/direvent.conf
. If a file name is
supplied as an argument to the program, that file will be read instead.
The configuration file syntax is discussed in detail in direvent.conf
This section provides only a short description of it.
Three types of comments are allowed: inline comments, that begin with a #
and extend to the end of line, and multi-line comments, which
comprise everything enclosed between /*
. Comments and
empty lines are ignored. Whitespace characters are ignored as well, except as
they serve to separate tokens.
A token is a string of consecutive characters from the following classes:
alphanumeric characters, underscores, dots, asteriscs, slashes, semicolons,
commercial at's, and dashes.
Any other sequence of characters must be enclosed in double quotation marks in
order to represent a single token.
Adjacent quoted strings are concatenated.
Configuration statements consist of a keyword and value separated by any amount
of whitespace and is terminated with a semicolon. A block statement is a
collection of statements enclosed in curly braces.
The most important configuration statement is watcher
. It is defined as
path PATHNAME [recursive [LEVEL]];
statement instructs direvent
to monitor the events
listed in EVENT-LIST
occurring in the directories specified by
s in path
statements (any number of path
statements can be given). When any such event is detected, the
will be executed.
Each directory defined with the recursive
keyword will be watched
recursively. This means that for each subdirectory created in it,
will install a watcher similar to that of its parent
directory. The optional LEVEL
can be used to set up a cut-off nesting
level, beyond which the recursive operation is disabled.
The rest of statements are optional. The user
statement can be used to
execute the COMMAND-LINE
as the user NAME
(provided, of course,
is started with root privileges). The timeout
specifies the maximum amount of time (in seconds) the command is allowed to
run. It defaults to 5. The environ
statement modifies the command
environment (see the following section). Finally, the option
supplies additional options. It can be used, for example, to divert the
command's output to syslog
The program's logging is controlled by the debug
- debug NUMBER;
- Sets the debugging level to NUMBER -- an integer
value between 0 and 3. Zero is the default and means the debugging is
disabled. The bigger the NUMBER the more detailed debugging
information will be output.
statement controls the syslog logging:
The pidfile statement instructs the program to write its PID to
the named file after disconnecting from the controlling terminal.
The handler to be executed on an event is defined by the command
statement in the watcher
configuration block (see
(5)). Before executing, the following operations are
- The current working directory is set to the directory where
the event occurred.
- If the environ statement is present in the watcher,
the environment is modified according to its rules. See the description of
the environ statement in direvent.conf(5).
- The standard input is closed.
- If the stdout option is supplied, the standard
output is captured and redirected to the syslog. Otherwise it is
- If the stderr option is supplied, the standard error
is captured and redirected to the syslog. Otherwise it is
- All file descriptors above 2 are closed.
- Macro variables are expanded. See the section
MACRO EXPANSION in direvent.conf(5). For example, if the
handler is about to be executed for the write event on the file
somefile, and the command definition was:
command "/libexec/handler -e '$genev_name' -f '$file'";
- then the resulting command line will be:
/libexec/handler -e 'open' -f 'somefile'
- Word splitting is performed on the resulting command line.
The first word is treated as the pathname of the program to be
- The program is invoked.
relies on the event monitoring API provided by the kernel.
the program uses inotify
The maximum number of watches a user process can have is controlled by the
system variable. Normally it is set to
8192, which is quite enough for most purposes. However, if you monitor a big
number or directories and/or are using recursive watchers, you may need more
watches. In that case, use sysctl
(8) to raise the limit, e.g.:
sysctl -w fs.inotify.max_user_watches=16384
Most GNU/Linux distributions provide the file /etc/sysctl.conf
be used to set this variable on startup.
The following system-dependent events are defined on systems that use
- A file was accessed.
- A file's metadata changed.
- A writable file was closed.
- An unwritable file closed.
- A file was created.
- A file was deleted.
- A file was modified.
- A file was moved into a monitored directory.
- A file was moved out from a monitored directory.
- A file was opened.
When compiled on BSD
systems (including Darwin
(2). This interface needs an open file handle for each file
in a monitored directory, which means that the number of watchers is limited
by the maximum number of open files. Use ulimit -n NUM
it to a higher number.
Since it operates on files, kqueue
does not provide direct support for
generic event. Direvent
works over this disadvantage
by keeping track of the contents of each monitored directory and rescanning it
each time a WRITE
system event is reported for it. It then generates
event for each file that appeared after the last scan. Such a
rescan can consume considerable time if a directory has a very large number of
files in it.
The following system-dependent events are available:
- The unlink() system call was called on the monitored
- A write occurred on the file.
- The file was extended.
- The file attributes have changed.
- The link count on the file changed.
- The file was renamed.
- Access to the file was revoked via revoke(2) or the
underlying file system was unmounted.
Essentially the same as BSD
. The main difference compared to Linux
is that on Darwin
the watchers are set after
disconnecting from the controlling terminal, because Darwin
(2) call and the event queue cannot be inherited by the child
- Successful termination.
- Command line usage error.
- Another error occurred.
Report bugs to <email@example.com>.
Copyright © 2012, 2013 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later
This is free software: you are free to change and redistribute it. There is NO
WARRANTY, to the extent permitted by law.