Direvent
1 Introduction
2 Overview
3 Quick Start
4 Invocation
5 Configuration
6 System Dependencies
7 How to Report a Bug
Appendix A Legacy Syntax of the 'environ' Statement
Appendix B GNU Free Documentation License
Concept Index
Direvent
1 Introduction
2 Overview
3 Quick Start
4 Invocation
5 Configuration
5.1 Configuration Syntax
5.1.1 Comments
5.1.2 Pragmatic Comments
5.1.3 Statements
5.2 Variable Expansion
5.3 General Settings
5.4 Syslog
5.5 Environment modification
5.6 Watcher
6 System Dependencies
6.1 GNU/Linux systems.
6.2 BSD systems
6.3 Darwin (Mac OS X)
7 How to Report a Bug
Appendix A Legacy Syntax of the 'environ' Statement
Appendix B GNU Free Documentation License
B.1 ADDENDUM: How to use this License for your documents
Concept Index
Direvent
********
This edition of the 'GNU Direvent' manual, last updated 25 June 2024,
documents GNU Direvent Version 5.4.
1 Introduction
**************
GNU 'direvent' monitors events in file system directories. For each
event that occurs in a set of pre-configured directories, the program
calls an external program associated with it, supplying it the
information about the event and the location within the file system
where it took place.
GNU 'direvent' provides an easy way to configure your system to react
immediately if certain files undergo changes. This may be helpful, for
example, to track changes in important configuration files.
Interfaces for tracking changes to file systems are highly
system-specific. GNU 'direvent' aims to provide a uniform and
system-independent command-level interface. As of version 5.4
'direvent' works with modern Linux kernels (since v. 2.6.13) and BSD
systems (FreeBSD, NetBSD, OpenBSD, Darwin).
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(1). 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.(2)
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.
---------- Footnotes ----------
(1) Obviously, the 'recursive' keyword is valid only if PATHNAME is a
directory.
(2) *Note path::, for a detailed description.
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. (*note
environment modification: environ.)
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.
*Note 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.
4 Invocation
************
The invocation syntax is:
direvent [OPTIONS] [CONFIG]
where OPTIONS are command line options discussed below and optional
CONFIG supplies the configuration file to use instead of the default
'/etc/direvent.conf'.
The options are:
'-d'
'--debug'
Increase debug level.
'-F NAME'
'--facility=NAME'
Set syslog facility.
'-f'
'--foreground'
Remain in foreground.
'-I DIR'
'--include=DIR'
Add DIR to the beginning of the include search path (*note include
search path::).
'-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. The
PRIO argument 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 FILE'
'--pidfile=FILE'
Upon successful startup store the PID of the daemon process in
FILE.
'-T COMMAND'
'--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 COMMAND terminates normally,
'direvent' exits with the code returned by it. If COMMAND
terminates on signal, 'direvent' exits with code '0' if this signal
was 'SIGHUP', and with code '2' otherwise.
The 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.
This mode is used in 'direvent' test suite. The idea is to
configure the handler (*note handler::) so that it sends 'SIGHUP'
to COMMAND before exiting. To this effect, the special macro
variable '$self_test_pid' is defined (*note variable expansion::)
to the PID of the running COMMAND process. For example, consider
configuration file 'test.conf', which contains the following:
watcher {
path /tmp;
command "/bin/kill -HUP $self_test_pid";
}
Then, the following command can be used to check whether 'direvent'
correctly reacts on file creation in the watched directory:
$ direvent --foreground \
--self-test 'touch /tmp/file && /usr/bin/sleep 20 && exit 1' \
test.conf
The command will return '0' if the handler was invoked, and '1' if
it was not.
'-t'
'--lint'
Check configuration file for errors and exit.
'-u NAME'
'--user=NAME'
Run as this user. This option overrides the 'user' configuration
statement (*note user: general settings.).
The following options are "informative". They cause the program to
display the requested piece of information and terminate:
'-H'
'--config-help'
Show configuration file summary.
'-h'
'--help'
Give a short usage summary.
'--usage'
Display available command line options.
'-V'
'--version'
Print program version.
5 Configuration
***************
5.1 Configuration Syntax
========================
The configuration file consists of statements and comments.
There are three classes of lexical tokens: keywords, values, and
separators. Blanks, tabs, newlines and comments, collectively called
"white space" are ignored except as they serve to separate tokens. Some
white space is required to separate otherwise adjacent keywords and
values.
5.1.1 Comments
--------------
"Comments" may appear anywhere where white space may appear in the
configuration file. There are two kinds of comments: single-line and
multi-line comments. "Single-line" comments start with '#' or '//' and
continue to the end of the line:
# This is a comment
// This too is a comment
"Multi-line" or "C-style" comments start with the two characters '/*'
(slash, star) and continue until the first occurrence of '*/' (star,
slash).
Multi-line comments cannot be nested. However, single-line comments
may well appear within multi-line ones.
5.1.2 Pragmatic Comments
------------------------
Pragmatic comments are similar to usual single-line comments, except
that they cause some changes in the way the configuration is parsed.
Pragmatic comments begin with a '#' sign and end with the next physical
newline character.
'#include <FILE>'
'#include "FILE"'
Include the contents of the file FILE. If FILE is an absolute file
name, the named file is included. An error message will be issued
if it does not exist.
If FILE contains wildcard characters ('*', '[', ']' or '?'), it is
interpreted as a shell globbing pattern and all files matching that
pattern are included, in lexicographical order. If no matching
files are found, the directive is replaced with an empty line.
Otherwise, the form with angle brackets searches for file in the
"include search path", while the second one looks for it in the
current working directory first, and, if not found there, in the
include search path. If the file is not found, an error message
will be issued.
"Include search path" is formed by two directory sets: the
user-defined search path, as defined by eventual '-I' (*note
include option::) command line options, and the standard include
search path, defined at compile time. The latter can be inspected
using the '--help' option.
The order of directories is as follows. First, 'direvent' scans
any directories given with '-I' options, in the same order as given
on the command line. If FILE is not found in any of them, the
standard include search path is scanned. It is defined at the
compile time and by default consists of two directories:
* 'PREFIX/share/direvent/include'
* 'PREFIX/share/direvent/5.4/include'
where PREFIX is the installation prefix. The default can be
changed when configuring the package. To inspect the actual
standard include search path at the runtime, run 'direvent --help',
and look for the string 'Include search path:' in its output.
'#include_once <FILE>'
'#include_once FILE'
Same as '#include', except that, if the FILE has already been
included, it will not be included again.
'#line NUM'
'#line NUM "FILE"'
This line causes the parser to believe, for purposes of error
diagnostics, that the line number of the next source line is given
by NUM and the current input file is named by FILE. If the latter
is absent, the remembered file name does not change.
'# NUM "FILE"'
This is a special form of '#line' statement, understood for
compatibility with the C preprocessor.
5.1.3 Statements
----------------
A "simple statement" consists of a keyword and value separated by any
amount of whitespace. Simple statement is terminated with a semicolon
(';').
The following is a simple statement:
standalone yes;
pidfile /var/run/direvent.pid;
A "keyword" begins with a letter and may contain letters, decimal
digits, underscores ('_') and dashes ('-'). Examples of keywords are:
'expression', 'output-file'.
A "value" can be one of the following:
number
A number is a sequence of decimal digits.
boolean
A boolean value is one of the following: 'yes', 'true', 't' or '1',
meaning "true", and 'no', 'false', 'nil', '0' meaning "false".
unquoted string
An unquoted string may contain letters, digits, and any of the
following characters: '_', '-', '.', '/', '@', '*', ':'.
quoted string
A quoted string is any sequence of characters enclosed in
double-quotes ('"'). A backslash appearing within a quoted string
introduces an "escape sequence", which is replaced with a single
character according to the following rules:
Sequence Replaced with
\a Audible bell character (ASCII 7)
\b Backspace character (ASCII 8)
\f Form-feed character (ASCII 12)
\n Newline character (ASCII 10)
\r Carriage return character (ASCII
13)
\t Horizontal tabulation character
(ASCII 9)
\v Vertical tabulation character
(ASCII 11)
\\ A single backslash ('\')
\" A double-quote.
Table 5.1: Backslash escapes
In addition, the sequence '\NEWLINE' is removed from the string.
This allows to split long strings over several physical lines,
e.g.:
"a long string may be\
split over several lines"
If the character following a backslash is not one of those
specified above, the backslash is ignored and a warning is issued.
Here-document
A "here-document" is a special construct that allows to introduce
strings of text containing embedded newlines.
The '<<WORD' construct instructs the parser to read all the
following lines up to the line containing only WORD, with possible
trailing blanks. Any lines thus read are concatenated together
into a single string. For example:
<<EOT
A multiline
string
EOT
The body of a here-document is interpreted the same way as a
double-quoted string, unless WORD is preceded by a backslash (e.g.
'<<\EOT') or enclosed in double-quotes, in which case the text is
read as is, without interpretation of escape sequences.
If WORD is prefixed with '-' (a dash), then all leading tab
characters are stripped from input lines and the line containing
WORD. Furthermore, if '-' is followed by a single space, all
leading whitespace is stripped from them. This allows to indent
here-documents in a natural fashion. For example:
<<- TEXT
The leading whitespace will be
ignored when reading these lines.
TEXT
It is important that the terminating delimiter be the only token on
its line. The only exception to this rule is allowed if a
here-document appears as the last element of a statement. In this
case a semicolon can be placed on the same line with its
terminating delimiter, as in:
help-text <<-EOT
A sample help text.
EOT;
list
A "list" is a comma-separated list of values. Lists are enclosed
in parentheses. The following example shows a statement whose
value is a list of strings:
option (stdout,stderr);
In any case where a list is appropriate, a single value is allowed
without being a member of a list: it is equivalent to a list with a
single member. This means that, e.g.
option wait;
is equivalent to
option (wait);
A "block statement" introduces a logical group of statements. It
consists of a keyword, followed by an optional value, and a sequence of
statements enclosed in curly braces, as shown in the example below:
syslog {
facility local0;
tag "direvent";
}
The closing curly brace may be followed by a semicolon, although this
is not required.
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'. *Note
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 (*note 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
(*note Handler environment: environ.).
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.
5.3 General Settings
====================
-- Config: user NAME
Sets the user to run as. The NAME argument must be a name of an
existing user.
-- Config: foreground BOOL
Run in foreground.
-- Config: pidfile FILE
Upon successful startup store the PID of the daemon process in
FILE.
-- Config: debug NUMBER
Set debug level. Valid NUMBER values are '0' (no debug) through
'4' (maximum verbosity).
5.4 Syslog
==========
While connected to the terminal, 'direvent' outputs its diagnostics and
debugging messages to the standard error. After disconnecting from the
controlling terminal it closes the first three file descriptors and
directs all its output to the syslog. When running in foreground mode,
its messages are sent both to the standard error and to the syslog.
The following configuration statement controls the syslog output:
syslog {
facility STRING;
tag STRING;
print-priority BOOL;
}
The statements are:
-- Config: facility STRING
Set syslog facility. The argument is one of the following: 'user',
'daemon', 'auth' or 'authpriv', 'mail', 'cron', 'local0' through
'local7' (case-insensitive), or a facility number.
-- Config: tag STRING
Tag syslog messages with 'string'. Normally the messages are
tagged with the program name.
-- Config: print-priority 'bool'
Prefix each message with its priority.
An example 'syslog' statement:
syslog {
facility local0;
print-priority yes;
}
5.5 Environment modification
============================
By default, each handler inherits the environment of the master
'direvent' process augmented with the following variables:
-- environment variable: DIREVENT_SYSEV_CODE
The system-dependent event code (*note the 'sysev_code' macro
variable: sysev_code.).
-- environment variable: DIREVENT_SYSEV_NAME
The system-dependent event name (*note the 'sysev_name' variable:
sysev_name.). If several system-dependent events are delivered,
this variable contains their names separated with single horizontal
space character.
-- environment variable: DIREVENT_GENEV_CODE
The generic event code (*note the 'genev_code' variable:
genev_code.).
-- environment variable: DIREVENT_GENEV_NAME
The generic event name (*note the 'genev_name' variable:
genev_name.). If several generic events are delivered, this
variable contains their names separated with single horizontal
space character.
-- environment variable: DIREVENT_FILE
The name of the affected file relative to the current working
directory (*note the 'file' variable: file.).
This environment can be further modified, using the 'environ'
configuration statement:
environ {
clear;
keep PATTERN;
set "NAME=VALUE";
eval "VALUE";
unset PATTERN;
}
Statements inside the 'environ' block define operations that modify
the environment. Their arguments undergo variable expansion (*note
variable expansion::). The 'clear' and 'keep' statements are executed
first. Then, the 'set' and 'unset' statements are applied in the order
of their appearance in the configuration.
-- environ: clear
Clears the environment by removing (unsetting) all variables,
except those listed in 'keep' statements, if such are given (see
below). The 'clear' statement is always executed first.
-- environ: keep PATTERN
-- environ: keep "NAME=VALUE"
Declares variables matching PATTERN as exempt from clearing. This
statement implies 'clear'.
The PATTERN is either a variable name or a globbing pattern
matching one or more names.
In the second form, the variable will be retained only if it has
the given VALUE. Note, that the argument must be quoted.
For example, the following configuration fragment removes from the
environment all variables except 'HOME', 'USER', 'PATH', and
variables beginning with 'DIREVENT_':
environ {
clear;
keep HOME;
keep USER;
keep PATH;
keep "DIREVENT_*";
}
-- environ: set "NAME=VALUE"
Assigns VALUE to the environment variable NAME. The value is
subject to "variable expansion" using the same syntax as in shell.
The 'set', 'eval', and 'unset' (see below) statements are executed
in order of their appearance. For example
environ {
set "MYLIB=$HOME/lib";
set "LD_LIBRARY_PATH=$LD_LIBRARY_PATH${LD_LIBRARY_PATH:+:}$MYLIB";
}
-- environ: eval "EXPR"
Perform variable expansion on EXPR and discard the result. This is
useful for side-effects. For example, to provide default value for
the 'LD_LIBRARY_PATH' variable, one may write:
environ {
eval "${LD_LIBRARY_PATH:=/usr/local/lib}";
}
-- environ: unset PATTERN
-- environ: unset "NAME=VALUE"
Unset environment variables matching PATTERN.
The PATTERN is either a variable name or a globbing pattern
matching one or more names.
In the second form, the variable will be unset only if it has the
given VALUE. Note, that the argument must be quoted.
E.g., the following will unset the 'LOGIN' variable:
unset LOGIN;
The following statement will unset all variables starting with
'LD_':
unset "LD_*";
Notice, that patterns containing wildcard characters must be
quoted.
5.6 Watcher
===========
The 'watcher' statement configures a single event watcher. A watcher
can control several events in multiple pathnames. Any number of
'watcher' statements is allowed in the configuration file, each of them
declaring a separate watcher.
watcher {
path PATHNAME [recursive [LEVEL]];
file REGEXP-LIST;
event EVENT-LIST;
command COMMAND-LINE;
user NAME;
timeout NUMBER;
environ { ... };
option STRING-LIST;
max-instances NUMBER;
}
Statements within a 'watcher' block are:
-- Config: path PATHNAME [recursive [NUMBER]]
Defines a pathname to watch. The PATHNAME argument must be the
name of a directory or file in the file system. If PATHNAME refers
to a directory, the watcher will watch events occurring for all
files within that directory. If the optional 'recursive' clause is
specified, this directory will be watched recursively, i.e. when
any subdirectory is created in it, 'direvent' will set up a watcher
for files in this subdirectory. This new watcher will be an exact
copy of the parent watcher, excepting for the pathnames. The
optional NUMBER parameter defines a cut-off nesting level for
recursive watching. If supplied, the recursive behaviour will
apply only to the directories that are nested below that level.
If PATHNAME refers to a regular file, the changes to that file will
be monitored. Obviously, in that case the 'recursive' keyword
makes no sense. If present, it will be silently ignored.
If the PATHNAME does not exist, GNU 'direvent' will defer setting
up the watcher until it is created. In order to do so, it will
find the longest directory prefix that exists in the file system
and will construct a "sentinel watcher" to monitor creation of the
next directory component. When this component is created, the
sentinel wakes up to set up a similar watcher for the next
directory component. Once it is done, the sentinel removes itself.
This process continues until the PATHNAME is eventually created.
When it happens, the last sentinel will activate the configured
watcher.
These actions are performed in reverse order upon removal of
PATHNAME or any of its trailing directory components.
Any number of 'path' statements can appear in a 'watcher' block.
At least one 'path' must be defined.
-- Config: file REGEXP-LIST
Selects which files are eligible for monitoring. The argument is a
list of globbing patterns (in the sense of *note fnmatch: (fnmatch
manual)fnmatch.) or extended regular expressions (*note Extended
regular expressions: (sed)Extended regexps.) one of which must
match the file name in order for the watcher to act on it. A '!'
in front of a pattern or regular expression indicates negation.
Such construct matches if the file name doesn't match the pattern.
Regular expressions must be surrounded by a pair of slashes,
optionally followed by the following flags:
b
Use basic regular expressions.
i
Enable case-insensitive matching.
For example:
file ("*.cfg", "/.*\\.jpg/i");
In this statement, the first string ('*.cfg') is treated as a shell
globbing pattern. The second one is a case-sensitive extended
regular expression.
-- Config: event STRING-LIST
Configures the filesystem events to watch for in the directories
declared by the 'path' statements. The argument is a list of event
names. Both generic and system-dependent event names are allowed.
Multiple 'event' statements accumulate.
A missing 'event' statement means "watch all events".
For example:
event (open,delete);
-- Config: command STRING
Defines a command to execute on event. The STRING is a command
line just as you would type it in 'sh'. It may contain macro and
environment variables (*note variable expansion::), which will be
expanded prior to execution.
For example:
command "/bin/prog -event $genev_name -file $file";
By default, the command is executed directly via 'execve' system
call. If 'shell' option is set, the command is executed via the
shell set in the 'SHELL' environment variable.
*Note handler environment::, for a detailed discussion of how the
command is executed.
-- Config: user STRING
Run command as this user.
-- Config: timeout NUMBER
Terminate the command if it runs longer than NUMBER seconds. The
default is 5 seconds.
-- Config: option STRING-LIST
A list of additional options. The following options are defined:
shell
Invoke the handler command via shell, as '$SHELL -c
"COMMAND"'. If this option is set, only macro variables are
expanded in COMMAND. Environment variable references are left
to be expanded by the shell. *Note variable expansion::.
wait
Wait for the program to terminate before handling next event
from the event queue. Normally the program runs
asynchronously.
stdout
Capture the standard output of the command and redirect it to
the syslog with the 'LOG_INFO' priority.
stderr
Capture the standard error of the command and redirect it to
the syslog with the 'LOG_ERR' priority.
-- Config: environ { ... }
Modify the handler command environment. *Note environ::, for a
detailed discussion of configuration statements within the curly
braces. This statement applies to the environment, modified by the
global 'environ' statement, if any.
For compatibility with earlier versions of the program, GNU
'direvent' also supports a "legacy syntax" of the 'environ'
statement. It is described in *note environ legacy syntax::.
-- Config: max-instances NUMBER
Sets maximum number of handler command instances that are allowed
to run simultaneously. Default is unlimited.
6 System Dependencies
*********************
'Direvent' relies on the event monitoring API provided by the kernel.
6.1 GNU/Linux systems.
======================
On GNU/Linux the program uses 'inotify'. *Note monitoring file system
events: (inotify(7))inotify.
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 to increase this number. In that case, use 'sysctl' (*note
configure kernel parameters at runtime: (sysctl(8))sysctl.) 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':
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.
6.2 BSD systems
===============
When compiled on BSD systems (including Darwin), 'direvent' uses
'kqueue' (*note kernel event notification mechanism:
(kqueue(2))kqueue.).
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' in order 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()' (*note revoke file
access: (revoke(2))revoke.) or the underlying file system was
unmounted.
On FreeBSD and NetBSD, the following events are additionally
available:
CLOSE
File not opened for writing was closed.
CLOSE_WRITE
File opened for writing was closed.
OPEN
File was opened.
READ
File was read.
The 'change' generic event (*note change: generic events.) is
supported only on FreeBSD and NetBSD.
6.3 Darwin (Mac OS X)
=====================
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' call and the
event queue cannot be inherited by the child process.
The 'change' generic event (*note change: generic events.) is not
supported on Darwin.
7 How to Report a Bug
*********************
Please, report bugs and suggestions to <bug-direvent@gnu.org.ua>.
You hit a bug if at least one of the conditions below is met:
* 'direvent' terminates on signal 11 (SIGSEGV) or 6 (SIGABRT).
* The program fails to do its job as described in this manual.
If you think you've found a bug, please be sure to include maximum
information available to reliably reproduce it, or at least to analyze
it. The information needed is:
* Version of the package you are using.
* Command line options and configuration file.
* Conditions under which the bug appears.
Any errors, typos or omissions found in this manual also qualify as
bugs. Please report them, if you happen to find any.
Appendix A Legacy Syntax of the 'environ' Statement
***************************************************
This appendix describes the syntax of the 'environ' statement used in
GNU 'direvent' versions 5.2 and earlier. The use of this legacy syntax
is discouraged. It is supported for backward compatibility only and
will be removed in future versions.
-- legacy syntax: environ ARGS
Modify command environment. Arguments are a single environment
modification directive, a whitespace-delimited list of directives,
or a proper list (*note list::) of directives.
The following directives are available. To facilitate switching to
the modern 'environ' syntax, the discussion below lists, for each legacy
directive, its modern syntax equivalent (*note environ::).
'-' (a single dash)
Clear the inherited environment, but retain the variables added by
'direvent' itself. The removed environment variables can be
selectively restored using the directives discussed below.
If used, this must be the first directive in the list.
The modern syntax equivalent is:
environ {
clear;
keep "DIREVENT_*";
}
'--' (double-dash)
Clear the entire environment, including the variables added by
'direvent'.
If used, this must be the first directive in the list.
The modern syntax equivalent is:
environ {
clear;
}
-NAME
Unset the variable NAME.
The modern syntax equivalent is
environ {
unset NAME;
}
-NAME=VAL
Unset the environment variable NAME only if its value is VAL. The
modern syntax equivalent is:
environ {
unset "NAME=VAL";
}
NAME
Restore the environment variable NAME. This directive is useful
after '-' or '--' to retain some variables from the environment.
The modern syntax equivalent is:
keep NAME;
NAME=VALUE
Define environment variable NAME to have given VALUE. It is
equivalent to:
environ {
keep "NAME=VALUE";
}
NAME+=VALUE
Retain variable NAME and append VALUE to its existing value. If no
such variable is present in the environment, it is created and
VALUE is assigned to it. However, if VALUE begins with a
punctuation character, this character is removed from it before the
assignment. This is convenient for using this construct with
environment variables like 'PATH', e.g.:
PATH+=:/sbin
In this example, if 'PATH' exists, ':/sbin' will be appended to it.
Otherwise, it will be created and '/sbin' will be assigned to it.
In modern syntax, use shell variable references, e.g.:
environ {
set "PATH=${PATH}${PATH:+:}/sbin";
}
NAME=+VALUE
Retain variable NAME and prepend VALUE to its existing value. If
no such variable is present in the environment, it is created and
VALUE is assigned to it. However, if VALUE ends with a punctuation
character, this character is removed from it before assignment.
In modern syntax, use shell variable references, e.g. instead of
doing
environ PATH=+/sbin:
use
environ {
set "PATH=/sbin${PATH:+:}$PATH";
}
Appendix B GNU Free Documentation License
*****************************************
Version 1.2, November 2002
Copyright (C) 2000, 2001, 2002, 2014 Free Software Foundation,
Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.
It complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless
of subject matter or whether it is published as a printed book. We
recommend this License principally for works whose purpose is
instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium,
that contains a notice placed by the copyright holder saying it can
be distributed under the terms of this License. Such a notice
grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The
"Document", below, refers to any such manual or work. Any member
of the public is a licensee, and is addressed as "you". You accept
the license if you copy, modify or distribute the work in a way
requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document
is in part a textbook of mathematics, a Secondary Section may not
explain any mathematics.) The relationship could be a matter of
historical connection with the subject or with related matters, or
of legal, commercial, philosophical, ethical or political position
regarding them.
The "Invariant Sections" are certain Secondary Sections whose
titles are designated, as being those of Invariant Sections, in the
notice that says that the Document is released under this License.
If a section does not fit the above definition of Secondary then it
is not allowed to be designated as Invariant. The Document may
contain zero Invariant Sections. If the Document does not identify
any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed
of pixels) generic paint programs or (for drawings) some widely
available drawing editor, and that is suitable for input to text
formatters or for automatic translation to a variety of formats
suitable for input to text formatters. A copy made in an otherwise
Transparent file format whose markup, or absence of markup, has
been arranged to thwart or discourage subsequent modification by
readers is not Transparent. An image format is not Transparent if
used for any substantial amount of text. A copy that is not
"Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format,
SGML or XML using a publicly available DTD, and standard-conforming
simple HTML, PostScript or PDF designed for human modification.
Examples of transparent image formats include PNG, XCF and JPG.
Opaque formats include proprietary formats that can be read and
edited only by proprietary word processors, SGML or XML for which
the DTD and/or processing tools are not generally available, and
the machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the
material this License requires to appear in the title page. For
works in formats which do not have any title page as such, "Title
Page" means the text near the most prominent appearance of the
work's title, preceding the beginning of the body of the text.
A section "Entitled XYZ" means a named subunit of the Document
whose title either is precisely XYZ or contains XYZ in parentheses
following text that translates XYZ in another language. (Here XYZ
stands for a specific section name mentioned below, such as
"Acknowledgements", "Dedications", "Endorsements", or "History".)
To "Preserve the Title" of such a section when you modify the
Document means that it remains a section "Entitled XYZ" according
to this definition.
The Document may include Warranty Disclaimers next to the notice
which states that this License applies to the Document. These
Warranty Disclaimers are considered to be included by reference in
this License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and
has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that you
add no other conditions whatsoever to those of this License. You
may not use technical measures to obstruct or control the reading
or further copying of the copies you make or distribute. However,
you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow the
conditions in section 3.
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly
have printed covers) of the Document, numbering more than 100, and
the Document's license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also clearly
and legibly identify you as the publisher of these copies. The
front cover must present the full title with all words of the title
equally prominent and visible. You may add other material on the
covers in addition. Copying with changes limited to the covers, as
long as they preserve the title of the Document and satisfy these
conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a machine-readable
Transparent copy along with each Opaque copy, or state in or with
each Opaque copy a computer-network location from which the general
network-using public has access to download using public-standard
network protocols a complete Transparent copy of the Document, free
of added material. If you use the latter option, you must take
reasonably prudent steps, when you begin distribution of Opaque
copies in quantity, to ensure that this Transparent copy will
remain thus accessible at the stated location until at least one
year after the last time you distribute an Opaque copy (directly or
through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of copies,
to give them a chance to provide you with an updated version of the
Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
under the conditions of sections 2 and 3 above, provided that you
release the Modified Version under precisely this License, with the
Modified Version filling the role of the Document, thus licensing
distribution and modification of the Modified Version to whoever
possesses a copy of it. In addition, you must do these things in
the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title
distinct from that of the Document, and from those of previous
versions (which should, if there were any, be listed in the
History section of the Document). You may use the same title
as a previous version if the original publisher of that
version gives permission.
B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in
the Modified Version, together with at least five of the
principal authors of the Document (all of its principal
authors, if it has fewer than five), unless they release you
from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in
the Addendum below.
G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document's
license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title,
and add to it an item stating at least the title, year, new
authors, and publisher of the Modified Version as given on the
Title Page. If there is no section Entitled "History" in the
Document, create one stating the title, year, authors, and
publisher of the Document as given on its Title Page, then add
an item describing the Modified Version as stated in the
previous sentence.
J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and
likewise the network locations given in the Document for
previous versions it was based on. These may be placed in the
"History" section. You may omit a network location for a work
that was published at least four years before the Document
itself, or if the original publisher of the version it refers
to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the section
all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered
in their text and in their titles. Section numbers or the
equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled
"Endorsements" or to conflict in title with any Invariant
Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option designate
some or all of these sections as invariant. To do this, add their
titles to the list of Invariant Sections in the Modified Version's
license notice. These titles must be distinct from any other
section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text
has been approved by an organization as the authoritative
definition of a standard.
You may add a passage of up to five words as a Front-Cover Text,
and a passage of up to 25 words as a Back-Cover Text, to the end of
the list of Cover Texts in the Modified Version. Only one passage
of Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document
already includes a cover text for the same cover, previously added
by you or by arrangement made by the same entity you are acting on
behalf of, you may not add another; but you may replace the old
one, on explicit permission from the previous publisher that added
the old one.
The author(s) and publisher(s) of the Document do not by this
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination all
of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice, and that you preserve all
their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name
but different contents, make the title of each such section unique
by adding at the end of it, in parentheses, the name of the
original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in
the list of Invariant Sections in the license notice of the
combined work.
In the combination, you must combine any sections Entitled
"History" in the various original documents, forming one section
Entitled "History"; likewise combine any sections Entitled
"Acknowledgements", and any sections Entitled "Dedications". You
must delete all sections Entitled "Endorsements."
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the documents
in all other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert
a copy of this License into the extracted document, and follow this
License in all other respects regarding verbatim copying of that
document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of a
storage or distribution medium, is called an "aggregate" if the
copyright resulting from the compilation is not used to limit the
legal rights of the compilation's users beyond what the individual
works permit. When the Document is included an aggregate, this
License does not apply to the other works in the aggregate which
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half
of the entire aggregate, the Document's Cover Texts may be placed
on covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic
form. Otherwise they must appear on printed covers that bracket
the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also
include the original English version of this License and the
original versions of those notices and disclaimers. In case of a
disagreement between the translation and the original version of
this License or a notice or disclaimer, the original version will
prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to
Preserve its Title (section 1) will typically require changing the
actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided for under this License. Any other
attempt to copy, modify, sublicense or distribute the Document is
void, and will automatically terminate your rights under this
License. However, parties who have received copies, or rights,
from you under this License will not have their licenses terminated
so long as such parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
<http://www.gnu.org/copyleft/>.
Each version of the License is given a distinguishing version
number. If the Document specifies that a particular numbered
version of this License "or any later version" applies to it, you
have the option of following the terms and conditions either of
that specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If the
Document does not specify a version number of this License, you may
choose any version ever published (not as a draft) by the Free
Software Foundation.
B.1 ADDENDUM: How to use this License for your documents
========================================================
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with
the Front-Cover Texts being LIST, and with the Back-Cover Texts
being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit
their use in free software.
Concept Index
*************
This is a general index of all issues discussed in this manual
* Menu:
* #include: Pragmatic Comments. (line 381)
* #include_once: Pragmatic Comments. (line 418)
* #line: Pragmatic Comments. (line 423)
* --config-help: Invocation. (line 329)
* --debug: Invocation. (line 258)
* --facility: Invocation. (line 260)
* --foreground: Invocation. (line 263)
* --help: Invocation. (line 331)
* --include: Invocation. (line 266)
* --lint: Invocation. (line 317)
* --pidfile: Invocation. (line 279)
* --self-test: Invocation. (line 283)
* --usage: Invocation. (line 334)
* --user: Invocation. (line 320)
* --version: Invocation. (line 336)
* -d: Invocation. (line 258)
* -F: Invocation. (line 260)
* -f: Invocation. (line 263)
* -H: Invocation. (line 329)
* -h: Invocation. (line 331)
* -I: Invocation. (line 266)
* -l: Invocation. (line 270)
* -P: Invocation. (line 279)
* -T: Invocation. (line 283)
* -t: Invocation. (line 317)
* -u: Invocation. (line 320)
* -V: Invocation. (line 336)
* ACCESS, linux event: linux. (line 1022)
* attrib: Overview. (line 98)
* ATTRIB, BSD: bsd. (line 1074)
* ATTRIB, linux event: linux. (line 1023)
* block statement: Statements. (line 552)
* boolean value: Statements. (line 456)
* BSD: bsd. (line 1046)
* change: Overview. (line 89)
* clear: environ. (line 772)
* CLOSE, FreeBSD: bsd. (line 1091)
* CLOSE, NetBSD: bsd. (line 1091)
* CLOSE_NOWRITE, linux event: linux. (line 1027)
* CLOSE_WRITE, FreeBSD: bsd. (line 1094)
* CLOSE_WRITE, linux event: linux. (line 1025)
* CLOSE_WRITE, NetBSD: bsd. (line 1094)
* command: watcher. (line 935)
* Comments in a configuration file: Comments. (line 358)
* comments, pragmatic: Pragmatic Comments. (line 376)
* configuration file statements: Statements. (line 437)
* create: Overview. (line 78)
* CREATE, linux event: linux. (line 1029)
* Darwin: darwin. (line 1108)
* debug: general settings. (line 683)
* delete: Overview. (line 82)
* DELETE, BSD: bsd. (line 1065)
* DELETE, linux event: linux. (line 1031)
* DIREVENT_FILE: environ. (line 751)
* DIREVENT_GENEV_CODE: environ. (line 741)
* DIREVENT_GENEV_NAME: environ. (line 745)
* DIREVENT_SYSEV_CODE: environ. (line 731)
* DIREVENT_SYSEV_NAME: environ. (line 735)
* environ: environ. (line 755)
* environ <1>: watcher. (line 981)
* environ <2>: environ legacy syntax.
(line 1145)
* environment, handler: environ. (line 731)
* escape sequence: Statements. (line 464)
* eval: environ. (line 811)
* event: watcher. (line 923)
* events: Overview. (line 69)
* events, generic: Overview. (line 76)
* events, system-dependent, on BSD: bsd. (line 1063)
* events, system-dependent, on Darwin: bsd. (line 1063)
* events, system-dependent, on linux: linux. (line 1019)
* EXTEND, BSD: bsd. (line 1071)
* facility: syslog. (line 706)
* facility, syslog: syslog. (line 707)
* FDL, GNU Free Documentation License: Copying This Manual.
(line 1251)
* file: variable expansion. (line 604)
* file <1>: watcher. (line 898)
* file system events: Overview. (line 69)
* foreground: general settings. (line 676)
* fs.inotify.max_user_watches: linux. (line 1006)
* generic events: Overview. (line 76)
* genev_code: variable expansion. (line 607)
* genev_name: variable expansion. (line 611)
* GNU/Linux: linux. (line 1003)
* Handler environment variables: environ. (line 731)
* handler execution environment: Quick start. (line 220)
* handler, defining: watcher. (line 936)
* handler, introduced: Overview. (line 102)
* here-document: Statements. (line 496)
* include directories, preprocessor: Pragmatic Comments. (line 398)
* include search path, preprocessor: Pragmatic Comments. (line 398)
* inotify: linux. (line 1003)
* keep: environ. (line 777)
* keep <1>: environ. (line 778)
* kqueue: bsd. (line 1046)
* LINK, BSD: bsd. (line 1077)
* linux kernel: linux. (line 1003)
* list: Statements. (line 536)
* logging: syslog. (line 690)
* Mac OS X: darwin. (line 1108)
* macro expansion: variable expansion. (line 567)
* max-instances: watcher. (line 991)
* MODIFY, linux event: linux. (line 1033)
* MOVED_FROM, linux event: linux. (line 1035)
* MOVED_TO, linux event: linux. (line 1037)
* multi-line comments: Comments. (line 366)
* number of open file descriptors: bsd. (line 1050)
* number of watches, linux: linux. (line 1006)
* OPEN, FreeBSD: bsd. (line 1097)
* OPEN, linux event: linux. (line 1039)
* OPEN, NetBSD: bsd. (line 1097)
* option: watcher. (line 959)
* path: watcher. (line 864)
* pidfile: general settings. (line 679)
* pragmatic comments: Pragmatic Comments. (line 376)
* preprocessor include search path: Pragmatic Comments. (line 398)
* print-priority: syslog. (line 715)
* quoted string: Statements. (line 464)
* READ, FreeBSD: bsd. (line 1098)
* RENAME, BSD: bsd. (line 1080)
* REVOKE, BSD: bsd. (line 1083)
* self-test mode: Invocation. (line 283)
* self_test_pid: variable expansion. (line 627)
* sentinel: watcher. (line 881)
* set: environ. (line 800)
* shell, watcher option: watcher. (line 963)
* simple statements: Statements. (line 437)
* single-line comments: Comments. (line 358)
* statement, block: Statements. (line 552)
* statement, simple: Statements. (line 437)
* statements, configuration file: Statements. (line 437)
* stdout, watcher option: watcher. (line 974)
* strerr, watcher option: watcher. (line 978)
* string, quoted: Statements. (line 464)
* string, unquoted: Statements. (line 460)
* sysctl: linux. (line 1006)
* sysctl.conf: linux. (line 1016)
* sysev_code: variable expansion. (line 617)
* sysev_name: variable expansion. (line 621)
* syslog: syslog. (line 690)
* syslog facility: syslog. (line 707)
* syslog tag: syslog. (line 712)
* system-dependent events on BSD: bsd. (line 1063)
* system-dependent events on Darwin: bsd. (line 1063)
* system-dependent events, linux: linux. (line 1019)
* tag: syslog. (line 711)
* tag, syslog: syslog. (line 712)
* timeout: watcher. (line 955)
* unset: environ. (line 820)
* unset <1>: environ. (line 821)
* user: general settings. (line 672)
* user <1>: watcher. (line 952)
* variable expansion: variable expansion. (line 567)
* wait, watcher option: watcher. (line 969)
* watcher declaration: watcher. (line 850)
* watcher declaration, summary: Overview. (line 131)
* watcher, complete description: watcher. (line 845)
* watcher, introduced: Overview. (line 102)
* write: Overview. (line 85)
* WRITE, BSD: bsd. (line 1068)