Provided by: direvent_5.0.90-1_amd64 bug


       direvent - directory event monitor


       direvent  [-HVdfh]  [-F NAME] [-P FILE] [-l PRIO] [-T COMMAND] [--debug] [--facility=NAME]
       [--foreground] [--pidfile=FILE] [--self-test=COMMAND] [--user=NAME] [CONFIG]

       direvent -h
       direvent --help

       direvent -H
       direvent --config-help

       direvent --usage

       direvent -V
       direvent --version


       GNU Direvent 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:

       create A file was created;

       delete A file was deleted;

       write  A file was written to;

       attrib 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 direvent can  trace
       various  system-dependent  events,  which may offer a better resolution.  These events are
       described in the section SYSTEM DEPENDENCIES below.

       A watcher is a configuration entity within direvent which 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  section

       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 section above).


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

       -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 process.

              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

       -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(5).  This section
       provides only a short description of it.

       Three types of comments are allowed: inline comments, that begin with a # or // and extend
       to the end of line, and multi-line comments, which comprise everything enclosed between /*
       and */.  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

       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 follows:

         watcher {
             path PATHNAME [recursive [LEVEL]];
             event EVENT-LIST;
             command COMMAND-LINE;
             user NAME;
             timeout NUMBER;
             environ ENV-SPEC;
             option STRING-LIST;

       Each watcher statement instructs direvent to  monitor  the  events  listed  in  EVENT-LIST
       occurring in the directories specified by PATHNAMEs in path statements (any number of path
       statements can be given).  When any such event  is  detected,  the  COMMAND-LINE  will  be

       Each directory defined with the recursive keyword will be watched recursively.  This means
       that for each subdirectory created in it, direvent 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, that direvent 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 statement 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 and syslog statements.

       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.

       The syslog statement controls the syslog logging:

         syslog {
             facility STRING;
             tag STRING;
             print-priority BOOL;

       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 direvent.conf(5)).  Before executing,  the  following  operations
       are performed:

       1.     The current working directory is set to the directory where the event occurred.

       2.     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

       3.     The standard input is closed.

              If the stdout option is supplied, the standard output is captured and redirected to
              the syslog.  Otherwise it is closed.

              If the stderr option is supplied, the standard error is captured and redirected  to
              the syslog.  Otherwise it is closed.

              All file descriptors above 2 are closed.

       4.     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'

       5.     Word  splitting  is  performed  on  the  resulting command line.  The first word is
              treated as the pathname of the program to be executed.

       6.     The program is invoked.


       Direvent relies on the event monitoring API provided by the kernel.


       On Linux the program uses inotify(7).

       The  maximum  number  of  watches  a  user  process  can  have  is   controlled   by   the
       fs.inotify.max_user_watches  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 which can be  used  to  set
       this variable on startup.

       The following system-dependent events are defined on systems that use inotify(7):

       ACCESS A file was accessed.

       ATTRIB A file's metadata changed.

              A writable file was closed.

              An unwritable file closed.

       CREATE A file was created.

       DELETE A file was deleted.

       MODIFY A file was modified.

              A file was moved into a monitored directory.

              A file was moved out from a monitored directory.

       OPEN   A file was opened.


       When  compiled on BSD systems (including Darwin), direvent uses kqueue(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 to
       raise it to a higher number.

       Since it operates on files, kqueue does not provide direct support for the create  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 the open 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

       The following system-dependent events are available:

       DELETE The unlink() system call was called on the monitored file.

       WRITE  A write occurred on the file.

       EXTEND The file was extended.

       ATTRIB The file attributes have changed.

       LINK   The link count on the file changed.

       RENAME The file was renamed.

       REVOKE Access  to  the  file  was  revoked via revoke(2) or the underlying file system was


       Essentially the same as BSD.  The main difference compared to Linux and  BSD  is  that  on
       Darwin  the  watchers  are  set after disconnecting from the controlling terminal, because
       Darwin lacks the rfork(2) call and the event  queue  cannot  be  inherited  by  the  child


       0      Successful termination.

       1      Command line usage error.

       2      Another error occurred.


       direvent.conf(5), inotify(7), kqueue(2).


       Sergey Poznyakoff


       Report bugs to <>.


       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.