Provided by: direvent_5.0.90-1_i386 bug

NAME

       direvent - directory event monitor

SYNOPSIS

       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

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.

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