diff options
| -rw-r--r-- | NEWS | 20 | ||||
| -rw-r--r-- | doc/direvent.8 | 7 | ||||
| -rw-r--r-- | doc/direvent.texi | 57 |
3 files changed, 68 insertions, 16 deletions
@@ -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. |