Provided by: direvent_5.1-1_amd64 bug

NAME

       direvent - directory event monitor

SYNOPSIS

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

       direvent -h
       direvent --help

       direvent -H
       direvent --config-help

       direvent --usage

       direvent -V
       direvent --version

DESCRIPTION

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

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

OPTIONS

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

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

       -h, --help
              Output a terse help summary and exit.

       -H, --config-help
              Describe configuration file syntax.

       --usage
              Show available command line options.

       -V, --version
              Print program version and copyright information.

CONFIGURATION

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

       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.

HANDLER ENVIRONMENT

       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
              direvent.conf(5).

       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.

SYSTEM DEPENDENCIES

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

Linux

       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.

       CLOSE_WRITE
              A writable file was closed.

       CLOSE_NOWRITE
              An unwritable file closed.

       CREATE A file was created.

       DELETE A file was deleted.

       MODIFY A file was modified.

       MOVED_FROM
              A file was moved into a monitored directory.

       MOVED_TO
              A file was moved out from a monitored directory.

       OPEN   A file was opened.

BSD

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

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

Darwin

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

EXIT CODE

       0      Successful termination.

       1      Command line usage error.

       2      Another error occurred.

SEE ALSO

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

AUTHORS

       Sergey Poznyakoff

BUG REPORTS

       Report bugs to <bug-direvent@gnu.org.ua>.

COPYRIGHT

       Copyright © 2012, 2013 Sergey Poznyakoff
       License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
       This is free software: you are free to change and redistribute it.  There is NO  WARRANTY,
       to the extent permitted by law.