aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--NEWS20
-rw-r--r--doc/direvent.87
-rw-r--r--doc/direvent.texi57
3 files changed, 68 insertions, 16 deletions
diff --git a/NEWS b/NEWS
index fd5c4e3..09e26a6 100644
--- a/NEWS
+++ b/NEWS
@@ -1,14 +1,32 @@
-direvent -- history of user-visible changes. 2016-08-13
+direvent -- history of user-visible changes. 2016-08-25
Copyright (C) 2012-2016 Sergey Poznyakoff
See the end of file for copying conditions.
Please send direvent bug reports to <bug-direvent@gnu.org.ua>
Version 5.1.90 (Git)
+* The path statement can refer to a regular file.
+
+Prior versions of direvent required that the argument to the "path"
+statement refer to an existing directory. This requirement is now
+lifted. The pathname can refer to any type of file (not only a
+directory). Moreover, the file is not required to exist. If it does
+not exist, direvent will set up an auxiliary watcher (called a
+"sentinel"), that will wake up upon creation of the file with that
+pathname and will set up the configured watcher once it is created.
+
+The process is reversed when the file referred to by the "path"
+statement is deleted. In that case, the configured watcher is
+deactivated and a sentinel is set up which will bring it back when the
+destination file or directory is created.
+
+This mode of operation ensures that the configured watcher will always
+be operational.
+
* Fix watcher removal on BSD-like systems.
* Configuration changes
** multiple environ statements
diff --git a/doc/direvent.8 b/doc/direvent.8
index 03644ff..0d7f73f 100644
--- a/doc/direvent.8
+++ b/doc/direvent.8
@@ -10,13 +10,13 @@
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with direvent. If not, see <http://www.gnu.org/licenses/>.
-.TH DIREVENT 8 "June 20, 2016" "DIREVENT" "Direvent User Reference"
+.TH DIREVENT 8 "August 25, 2016" "DIREVENT" "Direvent User Reference"
.SH NAME
direvent \- directory event monitor
.SH SYNOPSIS
\fBdirevent\fR [\fB\-HVdfh\fR] [\fB\-F\fR \fINAME\fR]\
[\fB\-P\fR \fIFILE\fR]\
[\fB\-l\fR \fIPRIO\fR]\
@@ -252,12 +252,17 @@ the \fICOMMAND\-LINE\fR will be executed.
Each directory defined with the \fBrecursive\fR keyword will be
watched recursively. This means that for each subdirectory created in
it, \fBdirevent\fR will install a watcher similar to that of its parent
directory. The optional \fILEVEL\fR can be used to set up a cut-off
nesting level, beyond which the recursive operation is disabled.
.PP
+The \fIPATHNAME\fR is not required to be a directory, it can as well
+be a file of any type. This file is not required to exist, either. If
+it does not, \fBdirevent\fR will defer configuring the watcher until
+the file is eventually created.
+.PP
The rest of statements are optional. The \fBuser\fR statement can be
used to execute the \fICOMMAND\-LINE\fR as the user \fINAME\fR
(provided, of course, that \fBdirevent\fR is started with root
privileges). The \fBtimeout\fR specifies the maximum amount of time
(in seconds) the command is allowed to run. It defaults to 5. The
\fBenviron\fR statement modifies the command environment (see the
diff --git a/doc/direvent.texi b/doc/direvent.texi
index 6781ac5..e307bf2 100644
--- a/doc/direvent.texi
+++ b/doc/direvent.texi
@@ -152,14 +152,14 @@ directories with a set of events and instructs @command{direvent} to
run a specified external command when any of these events occur in any
of these directories. This external command (called a @dfn{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
-@command{direvent} reads at startup. This file has a simple and easy
-to use syntax.
+@command{direvent} reads at startup. The following outlines its
+syntax:
Three types of comments are allowed: inline comments, that begin with
a @samp{#} or @samp{//} and extend to the end of line, and multi-line
comments, which comprise everything enclosed between @samp{/*} and
@samp{*/}. Comments and empty lines are ignored. Whitespace
characters are ignored as well, except as they serve to separate
@@ -176,13 +176,13 @@ 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.
@cindex watcher declaration, summary
-The following block statement declares a watcher:
+A watcher is declared using the following block statement:
@example
@group
watcher @{
path @var{pathname} [recursive [@var{level}]];
file @var{pattern-list};
@@ -205,12 +205,21 @@ the supplied @var{command-line} will be executed.
Each directory defined with the @code{recursive} keyword will be
watched recursively. This means that for each subdirectory created in
it, @command{direvent} will install a watcher similar to that of its parent
directory. Optional @var{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 @code{path} statement to refer to a
+directory. However, it is not a requirement. The @var{pathname}
+argument can as well point to any other type of
+file@footnote{Obviously, the @samp{recursive} keyword is valid only if
+@var{pathname} is a directory.}. Moreover, it is not required to
+exist, either. If it does not, @GNUDIREVENT{} will remember the
+watcher definition and will set it up when the @var{pathname} is
+eventually created.@footnote{@xref{path}, for a detailed description.}
+
The rest of statements are optional. The @code{file} statement
instructs @GNUDIREVENT{} to react only if the event concerned the
file whose name matches one of the patterns given in its argument.
The @code{user} statement can be used to execute the
@var{command-line} as the user @var{name} (provided, of course, that
@command{direvent} is started with root privileges). The
@@ -878,13 +887,13 @@ syslog @{
@node watcher
@section Watcher
@cindex watcher, complete description
The @samp{watcher} statement configures a single event watcher. A watcher can
control several events in multiple pathnames. Any number of @code{watcher}
-statements is allowed in the configuration file, each one of them declaring
+statements is allowed in the configuration file, each of them declaring
a separate watcher.
@cindex watcher declaration
@example
@group
watcher @{
@@ -899,24 +908,44 @@ watcher @{
@}
@end group
@end example
The statements within a @code{watcher} block are:
+@anchor{path}
@deffn {Config} path @var{pathname} [recursive [@var{number}]]
Defines a pathname to watch. The @var{pathname} argument must be the
-name of an existing directory in the file system. The watcher will
-watch events occurring for all files within that directory. If the
-optional @code{recursive} clause is specified, this directory will be
-watched recursively, i.e. when any subdirectory is created in it,
-@command{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 @var{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.
+name of a directory or file in the file system. If @var{pathname}
+refers to a directory, the watcher will watch events occurring for all
+files within that directory. If the optional @code{recursive} clause
+is specified, this directory will be watched recursively, i.e. when
+any subdirectory is created in it, @command{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 @var{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 @var{pathname} refers to a regular file, the changes to that file
+will be monitored. Obviously, in that case the @samp{recursive}
+keyword makes no sense. If present, it will be silently ignored.
+
+@cindex sentinel
+If the @var{pathname} does not exist, @GNUDIREVENT{} 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 @dfn{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 @var{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
+@var{pathname} or any of its trailing directory components.
Any number of @code{path} statements can appear in a @code{watcher} block.
At least one @code{path} must be defined.
@end deffn
@deffn {Config} file @var{regexp-list}

Return to:

Send suggestions and report system problems to the System administrator.