summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org>2016-08-25 19:29:06 (GMT)
committer Sergey Poznyakoff <gray@gnu.org>2016-08-25 19:29:47 (GMT)
commitd744882ee0c3295af1abd8ba80ae3598838c7c16 (patch) (side-by-side diff)
tree0e0ace1f318b183621d8a7ff438a5b89e4f8d19c
parente02fe00e6d2e83bc61764932f703831535105e5b (diff)
downloaddirevent-d744882ee0c3295af1abd8ba80ae3598838c7c16.tar.gz
direvent-d744882ee0c3295af1abd8ba80ae3598838c7c16.tar.bz2
Update the documentation
Diffstat (more/less context) (ignore whitespace changes)
-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,4 +1,4 @@
-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.
@@ -6,6 +6,24 @@ 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
diff --git a/doc/direvent.8 b/doc/direvent.8
index 03644ff..0d7f73f 100644
--- a/doc/direvent.8
+++ b/doc/direvent.8
@@ -13,7 +13,7 @@
.\"
.\" 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
@@ -255,6 +255,11 @@ 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
diff --git a/doc/direvent.texi b/doc/direvent.texi
index 6781ac5..e307bf2 100644
--- a/doc/direvent.texi
+++ b/doc/direvent.texi
@@ -155,8 +155,8 @@ 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
@@ -179,7 +179,7 @@ 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
@@ -208,6 +208,15 @@ 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.
@@ -881,7 +890,7 @@ syslog @{
@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
@@ -902,18 +911,38 @@ watcher @{
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.

Return to:

Send suggestions and report system problems to the System administrator.