2 Overview

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 program reacts by invoking an external command configured for that event.

File system events can be divided into two major groups. The system-dependent events are specific for each particular kernel interface. In the contrast, generic events don’t depend on the underlying system. They provide a higher level of abstraction and make it possible to port GNU direvent configurations between various systems and architectures.

The generic events are:

generic event: create

A file was created. This includes files moved from another directory.

generic event: delete

A file was deleted or moved to another directory.

generic event: write

A file was written to. This does not imply that the file was closed.

generic event: change

A file was modified and closed. This is a compound event, i.e. it is delivered when a system event that means that the file opened for writing was closed (CLOSE_WRITE), is delivered for a file on which one or more write events have been previously delivered. As such it depends on the operating system ability to deliver the CLOSE_WRITE event. Linux and FreeBSD have this ability. Many other systems, such as NetBSD and Darwin, don’t.

generic event: attrib

File attributes have changed. This includes changes in the file ownership, mode, link count, etc.

A watcher is a configuration entity that associates a set of directories with a set of events and instructs direvent 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 it from the environment variables, or from its command line.

Watchers are defined in the configuration file, which direvent reads at startup. The following outlines its syntax:

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

A configuration statement consists 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.

A watcher is declared using the following block statement:

watcher {
    path pathname [recursive [level]];
    file pattern-list;
    event  event-list;
    command command-line;
    user name;
    timeout number;
    environ { ... };
    option string-list;
}

Each watcher statement instructs direvent to monitor events from event-list occurring in directories specified by pathnames in path statements (any number of path statements can be given). When any such event is detected, the supplied 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. Optional level statement can be used to set up a cut-off nesting level, beyond which the recursive operation is disabled.

It is a common practice for the path statement to refer to a directory. However, it is not a requirement. The pathname argument can as well point to any other type of file¹. Moreover, it is not required to exist, either. If it does not, GNU direvent will remember the watcher definition and will set it up when the pathname is eventually created.²

The rest of statements are optional. The file statement instructs GNU direvent to react only if the event concerned the file whose name matches one of the patterns given in its argument. 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. Finally, the option statement supplies additional options. It can be used, for example, to divert the command’s output to syslog.