3 Quick Start

Let’s suppose you have a directory where users can upload their files and you want these files to be processed right after upload, in real time. Let this directory be /home/ftp/incoming and the program to process the upload be /usr/bin/upload. Let’s also suppose that this program expects name of the uploaded file as its argument.

To make direvent handle this task, you would need to create a watcher for the upload directory which would handle the ‘create’ event:

watcher {
    path /home/ftp/incoming;
    event create;
    # more statements follow...

On this event, the watcher is to invoke /usr/bin/upload with the name of the created file as an argument. To make it possible, the direvent configuration file provides macro variables, which can be used in the command argument at configuration time and which are expanded to the actual values before the command is executed. Macro variables are referred to using the same syntax as shell variables: a dollar sign followed by the variable name, optionally enclosed in curly braces. The ‘file’ variable is expanded to the name of the file for which the event is reported. This name is relative to the current working directory which, by the time the handler is executed, is set to the directory where the event occurred. Thus, the handler can be configured as:

    command "/usr/bin/upload $file";

To summarize, the watcher declaration is:

watcher {
    path /home/ftp/incoming;
    event create;
    command "/usr/bin/upload $file";
}

Before invoking the handler, the following operations are performed:

1. The current working directory is set to the directory where the event occurred.
2. If the global environ statement is present, the current environment is modified according to its rules.
3. If the environ statement is present in the watcher block, the environment is further modified according to its rules. (see environment modification)
4. The standard input is closed.
5. If the ‘stdout’ option is supplied, the standard output is captured and redirected to the syslog. Otherwise it is closed.
6. If the ‘stderr’ option is supplied, the standard error is captured and redirected to the syslog. Otherwise it is closed.
7. File descriptors above 2 are closed.
8. Macro variables are expanded in the command line. Unless the shell option is set, environment variables are expanded as well. See variable expansion.
9. If the shell option is set, the handler is invoked via the shell, as $SHELL -c "command".

   Otherwise, word splitting is performed on the resulting command line. The first word is treated as the pathname of the program, which is then invoked via the execve system call.