aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2014-08-22 19:02:39 +0300
committerSergey Poznyakoff <gray@gnu.org>2014-08-22 19:02:39 +0300
commit713bc0ca4b4ea3114d33f06c57c117de7f9fef11 (patch)
tree308cdef151241bd75676171da3a9e05e49d964c7
parent3a60622c75b8378c116bd37c8d78ab2b60a832e6 (diff)
downloaddirevent-713bc0ca4b4ea3114d33f06c57c117de7f9fef11.tar.gz
direvent-713bc0ca4b4ea3114d33f06c57c117de7f9fef11.tar.bz2
Update docs
-rw-r--r--doc/direvent.84
-rw-r--r--doc/direvent.texi119
2 files changed, 71 insertions, 52 deletions
diff --git a/doc/direvent.8 b/doc/direvent.8
index 683d9bc..b15ac01 100644
--- a/doc/direvent.8
+++ b/doc/direvent.8
@@ -10,15 +10,15 @@
.\" 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 "August 21, 2014" "DIREVENT" "Direvent User Reference"
+.TH DIREVENT 8 "August 22, 2014" "DIREVENT" "Direvent User Reference"
.SH NAME
-direvent \- directory content watcher
+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]\
[\fB\-\-debug\fR]
[\fB\-\-facility\fR=\fINAME\fR]\
diff --git a/doc/direvent.texi b/doc/direvent.texi
index e36a870..46b9a35 100644
--- a/doc/direvent.texi
+++ b/doc/direvent.texi
@@ -20,12 +20,16 @@
@syncodeindex pr cp
@syncodeindex kw cp
@syncodeindex fl cp
@include version.texi
+@macro GNUDIREVENT
+@acronym{GNU} @command{direvent}
+@end macro
+
@ifinfo
@dircategory Individual utilities
@direntry
* direvent: (direvent). Monitor changes in directories.
@end direntry
@end ifinfo
@@ -83,43 +87,45 @@ Appendices
@detailmenu
@end detailmenu
@end menu
@node Intro
@chapter Introduction
-@acronym{GNU} @command{Direvent} monitors events in the file system
-directories. For each event that occurs in a set of pre-configured
-directories, the program calls an external program associated with it,
-supplying it the information about the event and the location within
-the file system where it occured.
+@GNUDIREVENT{} monitors events in file system directories. For each
+event that occurs in a set of pre-configured directories, the program
+calls an external program associated with it, supplying it the
+information about the event and the location within the file system
+where it took place.
-@acronym{GNU} @command{Direvent} provides an easy way to configure
+@GNUDIREVENT{} provides an easy way to configure
your system to react immediately if certain files undergo changes.
-This may be helpful, for example, to track changes in the important
-configuration files. Interfaces for tracking changes to file systems
-are highly system-specific. @command{Direvent} aims to provide a uniform
+This may be helpful, for example, to track changes in important
+configuration files.
+
+Interfaces for tracking changes to file systems
+are highly system-specific. @GNUDIREVENT{} aims to provide a uniform
and system-independent command-level interface. As of version
@value{VERSION} @command{direvent} works with modern Linux kernels
(since v. 2.6.13) and BSD systems (FreeBSD, NetBSD, OpenBSD, Darwin).
@node Overview
@chapter Overview
-@command{Direvent} monitors a set of directories on the file system and
+@GNUDIREVENT{} monitors a set of directories on the file system and
reacts when a file system event occurs in any of them. Directories
and events to monitor are specified in the configuration file. When
an event occurs the utility reacts by invoking an external command
configured for that event.
@cindex events
@cindex file system events
-There are two kinds of events: @dfn{system-dependent events}, which are
-specific for each particular kernel interface, and @dfn{generic
-events}, which don't depend on the underlying system. Generic events
-provide a higher level of abstraction and make it possible to port
-direvent configurations between various systems and architectures
-without the need to rewrite them.
+File system events can be divided into two major groups. The
+@dfn{system-dependent events} are specific for each particular kernel
+interface. In the contrast, @dfn{generic events} don't depend on the
+underlying system. They provide a higher level of abstraction and
+make it possible to port @GNUDIREVENT{} configurations between various
+systems and architectures.
@cindex generic events
@cindex events, generic
The generic events are:
@table @asis
@@ -141,13 +147,13 @@ ownership, mode, link count, etc.
@cindex watcher, introduced
@cindex handler, introduced
A @dfn{watcher} is a configuration entity which associates a set of
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 its execution
+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.
@@ -164,81 +170,85 @@ slashes, semicolons, commercial at's, and dashes.
Any other sequence of characters must be enclosed in double quotation
marks in order to represent a single token.
Adjacent quoted strings are concatenated.
-Configuration statements consist of a keyword and value separated by
+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:
@example
watcher @{
path @var{pathname} [recursive [@var{level}]];
event @var{event-list};
command @var{command-line};
+ file @var{pattern-list};
user @var{name};
timeout @var{number};
environ @var{env-spec};
option @var{string-list};
@}
@end example
Each @code{watcher} statement instructs @command{direvent} to monitor
-the events listed in @var{event-list} occurring in the directories
+events listed in @var{event-list} occurring in the directories
specified by @var{pathname}s in @code{path} statements (any number of
@code{path} statements can be given). When any such event is detected,
-the @var{command-line} will be executed.
+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. The optional @var{level} can be used to set up a cut-off
+directory. Optional @var{level} statement can be used to set up a cut-off
nesting level, beyond which the recursive operation is disabled.
-The rest of statements are optional. 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 @code{timeout} specifies the maximum amount of time
-(in seconds) the command is allowed to run. It defaults to 5. The
-@code{environ} statement modifies the command environment. Finally,
-the @code{option} statement supplies additional options. It can be
-used, for example, to divert the command's output to syslog.
+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
+@code{timeout} specifies the maximum amount of time (in seconds) the
+command is allowed to run. It defaults to 5. The @code{environ}
+statement modifies the command environment. Finally, the
+@code{option} statement supplies additional options. It can be used,
+for example, to divert the command's output to syslog.
@node Quick start
@chapter Quick Start
Let's suppose you have a directory where users can upload their files
and you want these files to be processed right after upload, in real
time. Let this directory be @file{/home/ftp/incoming} and the program
to process the upload be @file{/usr/bin/upload}. Let's also suppose
-that this program expects the name of file as its argument.
+that this program expects name of the uploaded file as its argument.
To make @command{direvent} handle this task, you would need to create a
watcher for the upload directory which would handle the @samp{create} event:
@example
watcher @{
path /home/ftp/incoming;
event create;
# @r{more statements follow...}
@end example
-On this event the watcher is to invoke @file{/usr/bin/upload}
-supplying it the name of created file as an argument. To make it
-possible the @command{direvent} configuration file provides @dfn{macro
+On this event, the watcher is to invoke @file{/usr/bin/upload}
+with the name of created file as an argument. To make it
+possible, the @command{direvent} configuration file provides @dfn{macro
variables}, which can be used in the @code{command} argument at
configuration time and which are expanded to the actual values before
the command is executed. Macro variables are referred to using the
same syntax as shell variables: a dollar sign followed by the variable
name, optionally enclosed in curly braces. The @samp{file} variable
is expanded to the name of the file for which the event is reported.
-This name is relative to the current working directory which by the
-time the handler is executed is set to the directory where the event
+This name is relative to the current working directory which, by the
+time the handler is executed, is set to the directory where the event
occurred. Thus, the handler can be configured as:
@example
command "/usr/bin/upload $file";
@end example
@@ -321,20 +331,20 @@ Increase debug level.
@opindex --foreground
@item -f
@itemx --foreground
Remain in foreground.
@opindex -l
@item -l @var{prio}
-While connected to a terminal @command{direvent} outputs its diagnostics
+While connected to a terminal, @command{direvent} outputs its diagnostics
messages to stderr and, if configured, to syslog. This option
limits the amount of information output to the standard error.
The @var{prio} argument is one of the following priorities (in order
of increasing severity): @samp{debug}, @samp{info}, @samp{notice},
@samp{warning}, @samp{err}, @samp{crit}, @samp{alert}, @samp{emerg}.
When this option is given, only messages with the priority level equal
-to or greater than @var{prio} will be duplicated on the standard eraror.
+to or greater than @var{prio} will be duplicated on the standard error.
@end table
The following options are @dfn{informative}. They cause the program
to display the requested piece of information and terminate:
@table @option
@@ -631,41 +641,46 @@ this is not required.
@section Macro Expansion
@cindex macro expansion
Arguments of some statements undergo macro expansion before use.
During the macro expansion any occurrence of @samp{$@var{name}} is replaced
by the value of the macro @var{name}. Macro names follow the usual
convention: they begin with a letter and contain letters, digits and
-underscores. The curly braces around the @var{name} are optional.
+underscores. Curly braces around the @var{name} are optional.
They are required only if the macro reference is followed by a
character that is not to be interpreted as part of its name, as in
@samp{$@{command@}string}.
The following macros are defined:
@table @asis
+@anchor{$file}
@kwindex file, macro variable
@item file
Name of the file that triggered the event.
+@anchor{$sysev_code}
@kwindex sysev_code, macro variable
@item sysev_code
A system-dependent event code. It is a bitwise OR of the event codes
represented as a decimal number.
+@anchor{$sysev_name}
@kwindex sysev_name, macro variable
@item sysev_name
A system-dependent event name. If several events are reported, the
value of this variable is a list of event names separated by space
characters. Each name corresponds to a bit in @samp{sysev_code}.
@xref{System dependencies}, for a list of system-dependent event names.
+@anchor{$genev_code}
@kwindex genev_code, macro variable
@item genev_code
Generic (system-independent) event code. It is a bitwise OR of
the event codes represented as a decimal number.
+@anchor{$genev_name}
@kwindex genev_name, macro variable
@item genev_name
Generic event name. If several generic events are reported simultaneously, the
value of this variable is a list of event names separated by space
characters. Each name corresponds to a bit in @samp{$genev_code}.
@end table
@@ -692,13 +707,13 @@ Set debug level. Valid @var{number} values are @samp{0} (no debug) to @samp{3}
@end deffn
@node syslog
@section Syslog
@cindex syslog
@cindex logging
-While connected to the terminal @command{direvent} outputs its diagnostics and
+While connected to the terminal, @command{direvent} outputs its diagnostics and
debugging messages to the standard error. After disconnecting from the
controlling terminal it closes the first three file descriptors and directs
all its output to the syslog. When running in foreground mode, its
messages are sent both to the standard error and to the syslog.
The following configuration statement controls the syslog output:
@@ -808,13 +823,13 @@ Use basic regular expressions.
Enable case-insensitive matching.
@end table
For example:
@example
-file (*.cfg, /.*\\.jpg/i);
+file ("*.cfg", "/.*\\.jpg/i");
@end example
@noindent
In this statement, the first string (@samp{*.cfg}) is treated as a
shell globbing pattern. The second one is a case-sensitive extended
regular expression.
@@ -885,44 +900,48 @@ of @command{direvent} augmented with the following variables:
@cindex Handler environment variables
@cindex environment, handler
@table @env
@kwindex DIREVENT_SYSEV_CODE, environment variable
@item DIREVENT_SYSEV_CODE
-The system-dependent event code (see the @code{$sysev_code} variable).
+The system-dependent event code (@pxref{$sysev_code, the $sysev_code variable}).
@kwindex DIREVENT_SYSEV_NAME, environment variable
@item DIREVENT_SYSEV_NAME
-The system-dependent event name or names (see the @code{$sysev_name} variable).
+The system-dependent event name or names (@pxref{$sysev_name,
+the @code{$sysev_name} variable}).
@kwindex DIREVENT_GENEV_CODE, environment variable
@item DIREVENT_GENEV_CODE
-The generic event code (see the @code{$genev_code} variable).
+The generic event code (@pxref{$genev_code,the @code{$genev_code} variable}).
@kwindex DIREVENT_GENEV_NAME, environment variable
@item DIREVENT_GENEV_NAME
-The generic event name or names (see the @code{$genev_name} variable).
+The generic event name or names (@pxref{$genev_name, the @code{$genev_name} variable}).
@kwindex DIREVENT_FILE, environment variable
@item DIREVENT_FILE
The name of the affected file relative to the current working directory
-(see the @code{$file} variable).
+(@pxref{$file,the @code{$file} variable}).
@end table
@cindex environment modification
The @code{environ} statement allows for trimming the environment. Its
argument is a list of environment modification directives. Before
applying, each directive undergoes macro expansion (@pxref{macro
expansion}). The following directives are available:
@table @asis
-@item - (a single dash)
+@item @samp{-} (a single dash)
Clear the inherited environment, but retain the variables added by
-@command{direvent}. The removed environment variables can be selectively
-restored using the directives discussed below. This must be the first
-directive in the list.
+@command{direvent} itself. The removed environment variables can be selectively
+restored using the directives discussed below.
+
+If used, this must be the first directive in the list.
@item @samp{--} (double-dash)
Clear the entire environment, including the variables added by
-@command{direvent}. This must be the first directive in the list.
+@command{direvent}.
+
+If used, this must be the first directive in the list.
@item -@var{name}
Unset the variable @var{name}.
@item -@var{name}=@var{val}
Unset the environment variable @var{name} only if its value is @var{val}.

Return to:

Send suggestions and report system problems to the System administrator.