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