aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2016-08-25 22:29:06 +0300
committerSergey Poznyakoff <gray@gnu.org>2016-08-25 22:29:06 +0300
commit5b12866a27858cd902dd7bf1484d1536baa3c41a (patch)
tree3dab7a9edd8f3ac4095db5a42835bc198818199d
parent3a52a859855af393ddbff36684a1292e510b065f (diff)
downloaddirevent-5b12866a27858cd902dd7bf1484d1536baa3c41a.tar.gz
direvent-5b12866a27858cd902dd7bf1484d1536baa3c41a.tar.bz2
Update the documentationsentinel
-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 @@
1direvent -- history of user-visible changes. 2016-08-13 1direvent -- history of user-visible changes. 2016-08-25
2Copyright (C) 2012-2016 Sergey Poznyakoff 2Copyright (C) 2012-2016 Sergey Poznyakoff
3See the end of file for copying conditions. 3See the end of file for copying conditions.
4 4
@@ -6,6 +6,24 @@ Please send direvent bug reports to <bug-direvent@gnu.org.ua>
6 6
7Version 5.1.90 (Git) 7Version 5.1.90 (Git)
8 8
9* The path statement can refer to a regular file.
10
11Prior versions of direvent required that the argument to the "path"
12statement refer to an existing directory. This requirement is now
13lifted. The pathname can refer to any type of file (not only a
14directory). Moreover, the file is not required to exist. If it does
15not exist, direvent will set up an auxiliary watcher (called a
16"sentinel"), that will wake up upon creation of the file with that
17pathname and will set up the configured watcher once it is created.
18
19The process is reversed when the file referred to by the "path"
20statement is deleted. In that case, the configured watcher is
21deactivated and a sentinel is set up which will bring it back when the
22destination file or directory is created.
23
24This mode of operation ensures that the configured watcher will always
25be operational.
26
9* Fix watcher removal on BSD-like systems. 27* Fix watcher removal on BSD-like systems.
10 28
11* Configuration changes 29* 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 @@
13.\" 13.\"
14.\" You should have received a copy of the GNU General Public License along 14.\" You should have received a copy of the GNU General Public License along
15.\" with direvent. If not, see <http://www.gnu.org/licenses/>. 15.\" with direvent. If not, see <http://www.gnu.org/licenses/>.
16.TH DIREVENT 8 "June 20, 2016" "DIREVENT" "Direvent User Reference" 16.TH DIREVENT 8 "August 25, 2016" "DIREVENT" "Direvent User Reference"
17.SH NAME 17.SH NAME
18direvent \- directory event monitor 18direvent \- directory event monitor
19.SH SYNOPSIS 19.SH SYNOPSIS
@@ -255,6 +255,11 @@ it, \fBdirevent\fR will install a watcher similar to that of its parent
255directory. The optional \fILEVEL\fR can be used to set up a cut-off 255directory. The optional \fILEVEL\fR can be used to set up a cut-off
256nesting level, beyond which the recursive operation is disabled. 256nesting level, beyond which the recursive operation is disabled.
257.PP 257.PP
258The \fIPATHNAME\fR is not required to be a directory, it can as well
259be a file of any type. This file is not required to exist, either. If
260it does not, \fBdirevent\fR will defer configuring the watcher until
261the file is eventually created.
262.PP
258The rest of statements are optional. The \fBuser\fR statement can be 263The rest of statements are optional. The \fBuser\fR statement can be
259used to execute the \fICOMMAND\-LINE\fR as the user \fINAME\fR 264used to execute the \fICOMMAND\-LINE\fR as the user \fINAME\fR
260(provided, of course, that \fBdirevent\fR is started with root 265(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
155from the environment variables, or from its command line. 155from the environment variables, or from its command line.
156 156
157Watchers are defined in the configuration file, which 157Watchers are defined in the configuration file, which
158@command{direvent} reads at startup. This file has a simple and easy 158@command{direvent} reads at startup. The following outlines its
159to use syntax. 159syntax:
160 160
161Three types of comments are allowed: inline comments, that begin with 161Three types of comments are allowed: inline comments, that begin with
162a @samp{#} or @samp{//} and extend to the end of line, and multi-line 162a @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
179statement is a collection of statements enclosed in curly braces. 179statement is a collection of statements enclosed in curly braces.
180 180
181@cindex watcher declaration, summary 181@cindex watcher declaration, summary
182The following block statement declares a watcher: 182A watcher is declared using the following block statement:
183 183
184@example 184@example
185@group 185@group
@@ -208,6 +208,15 @@ it, @command{direvent} will install a watcher similar to that of its parent
208directory. Optional @var{level} statement can be used to set up a cut-off 208directory. Optional @var{level} statement can be used to set up a cut-off
209nesting level, beyond which the recursive operation is disabled. 209nesting level, beyond which the recursive operation is disabled.
210 210
211It is a common practice for the @code{path} statement to refer to a
212directory. However, it is not a requirement. The @var{pathname}
213argument can as well point to any other type of
214file@footnote{Obviously, the @samp{recursive} keyword is valid only if
215@var{pathname} is a directory.}. Moreover, it is not required to
216exist, either. If it does not, @GNUDIREVENT{} will remember the
217watcher definition and will set it up when the @var{pathname} is
218eventually created.@footnote{@xref{path}, for a detailed description.}
219
211The rest of statements are optional. The @code{file} statement 220The rest of statements are optional. The @code{file} statement
212instructs @GNUDIREVENT{} to react only if the event concerned the 221instructs @GNUDIREVENT{} to react only if the event concerned the
213file whose name matches one of the patterns given in its argument. 222file whose name matches one of the patterns given in its argument.
@@ -881,7 +890,7 @@ syslog @{
881@cindex watcher, complete description 890@cindex watcher, complete description
882The @samp{watcher} statement configures a single event watcher. A watcher can 891The @samp{watcher} statement configures a single event watcher. A watcher can
883control several events in multiple pathnames. Any number of @code{watcher} 892control several events in multiple pathnames. Any number of @code{watcher}
884statements is allowed in the configuration file, each one of them declaring 893statements is allowed in the configuration file, each of them declaring
885a separate watcher. 894a separate watcher.
886 895
887@cindex watcher declaration 896@cindex watcher declaration
@@ -902,18 +911,38 @@ watcher @{
902 911
903The statements within a @code{watcher} block are: 912The statements within a @code{watcher} block are:
904 913
914@anchor{path}
905@deffn {Config} path @var{pathname} [recursive [@var{number}]] 915@deffn {Config} path @var{pathname} [recursive [@var{number}]]
906Defines a pathname to watch. The @var{pathname} argument must be the 916Defines a pathname to watch. The @var{pathname} argument must be the
907name of an existing directory in the file system. The watcher will 917name of a directory or file in the file system. If @var{pathname}
908watch events occurring for all files within that directory. If the 918refers to a directory, the watcher will watch events occurring for all
909optional @code{recursive} clause is specified, this directory will be 919files within that directory. If the optional @code{recursive} clause
910watched recursively, i.e. when any subdirectory is created in it, 920is specified, this directory will be watched recursively, i.e. when
911@command{direvent} will set up a watcher for files in this 921any subdirectory is created in it, @command{direvent} will set up a
912subdirectory. This new watcher will be an exact copy of the parent 922watcher for files in this subdirectory. This new watcher will be an
913watcher, excepting for the pathnames. The optional @var{number} 923exact copy of the parent watcher, excepting for the pathnames. The
914parameter defines a cut-off nesting level for recursive watching. If 924optional @var{number} parameter defines a cut-off nesting level for
915supplied, the recursive behaviour will apply only to the directories 925recursive watching. If supplied, the recursive behaviour will apply
916that are nested below that level. 926only to the directories that are nested below that level.
927
928If @var{pathname} refers to a regular file, the changes to that file
929will be monitored. Obviously, in that case the @samp{recursive}
930keyword makes no sense. If present, it will be silently ignored.
931
932@cindex sentinel
933If the @var{pathname} does not exist, @GNUDIREVENT{} will defer
934setting up the watcher until it is created. In order to do so,
935it will find the longest directory prefix that exists in the file
936system and will construct a @dfn{sentinel watcher} to monitor
937creation of the next directory component. When this component is
938created, the sentinel wakes up to set up a similar watcher for the
939next directory component. Once it is done, the sentinel removes
940itself. This process continues until the @var{pathname} is eventually
941created. When it happens, the last sentinel will activate the
942configured watcher.
943
944These actions are performed in reverse order upon removal of
945@var{pathname} or any of its trailing directory components.
917 946
918Any number of @code{path} statements can appear in a @code{watcher} block. 947Any number of @code{path} statements can appear in a @code{watcher} block.
919At least one @code{path} must be defined. 948At least one @code{path} must be defined.

Return to:

Send suggestions and report system problems to the System administrator.