5.2 Variable Expansion

Arguments of some configuration statements undergo variable expansion before use. During variable expansion, variable references found in string are replaced with the actual values of the corresponding variables.

A variable reference has the form ‘$variable’ or ‘${variable}’, where variable is the variable name. The two forms are entirely equivalent. The form with curly braces is normally used if the variable name is immediately followed by an alphanumeric symbol, which will otherwise be considered part of it. This form also allows for specifying the action to take if the variable is undefined or expands to an empty value:

${variable:-word}

Use Default Values. If variable is unset or null, the expansion of word is substituted. Otherwise, the value of variable is substituted.

${variable:=word}

Assign Default Values. If variable is unset or null, the expansion of word is assigned to variable. The value of variable is then substituted.

${variable:?word}

Display Error if Null or Unset. If variable is null or unset, the expansion of word (or a message to that effect if word is not present) is output to the current logging channel. Otherwise, the value of variable is substituted.

${variable:+word}

Use Alternate Value. If variable is null or unset, nothing is substituted, otherwise the expansion of word is substituted.

Two kinds of variables take part in variable expansion: environment variables and macro variables. The latter are special variable-like entities defined by direvent to carry information about the event and its target file.

macro variable: file

Name of the file that triggered the event.

macro variable: genev_code

Generic (system-independent) event code. It is a bitwise OR of the event codes represented as a decimal number.

macro variable: genev_name

Generic event name. If several generic events are reported simultaneously, the value of this variable is a list of event names separated by space characters. Each name corresponds to a bit in ‘$genev_code’.

macro variable: sysev_code

A system-dependent event code. It is a bitwise OR of the event codes represented as a decimal number.

macro variable: sysev_name

A system-dependent event name. If several events are reported, the value of this variable is a list of event names separated by space characters. Each name corresponds to a bit in ‘sysev_code’. See System dependencies, for a list of system-dependent event names.

macro variable: self_test_pid

The PID of the external command started with the --self-test option (see self-test mode). If direvent is started without this option, this variable is not defined.

Statements whose arguments undergo variable expansion are: command and environ (all substatements and legacy syntax use). Although syntactically both environment and macro variables are treated the same way, there are some subtle differences between them that you should be aware of.

First of all, macro variables are not reflected in the environment of handlers. There are special environment variables for that purpose (see Handler environment).

Secondly, macro variables take precedence before the environment. It is possible, for example, that the environment variable ‘sysev_name’ is defined in the environment inherited by direvent or set using the environ statement. To ensure that such improper usage won’t affect functionality of the watchers, direvent unconditionally deletes from the environment any variables whose names coincide with macro variables.

When used in command argument and the shell option is set, macro variables are expanded whereas environment variables are not (they will be expanded later by the shell). Consider, for example, the following definition:

watcher {
   option shell;
   path "/tmp";
   command "$BINDIR/handler $file $DIREVENT_GENEV_CODE";
}

When an event wakes up this watcher, only $file will be expanded. Suppose that an event was delivered for file /tmp/myfile. Then, direvent will run the following command:

$SHELL -c '$BINDIR/handler myfile $DIREVENT_GENEV_CODE'

The remaining environment variable references will be expanded by the shell.