summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2014-09-01 17:00:50 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2014-09-01 19:16:03 (GMT)
commit9c10801c606eceda5b37d10f441a5b7d4cfb444a (patch) (side-by-side diff)
tree968a171e15c30dddba8471a9f0d528443d04b224
parent5fea0129bb54feb5bfa0deb0ce8e8403b1328079 (diff)
downloaddirevent-9c10801c606eceda5b37d10f441a5b7d4cfb444a.tar.gz
direvent-9c10801c606eceda5b37d10f441a5b7d4cfb444a.tar.bz2
Improve and document self-test mode
* src/direvent.c (self_test): Run the program as /bin/sh -c program. * doc/direvent.texi: Document self-test mode and missing options. * doc/direvent.8: Document self-test. * doc/direvent.conf.5: Likewise. * src/cmdline.opt: Fix option declarations.
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--doc/direvent.851
-rw-r--r--doc/direvent.conf.527
-rw-r--r--doc/direvent.texi129
-rw-r--r--src/cmdline.opt4
-rw-r--r--src/direvent.c23
5 files changed, 164 insertions, 70 deletions
diff --git a/doc/direvent.8 b/doc/direvent.8
index b15ac01..d72e06f 100644
--- a/doc/direvent.8
+++ b/doc/direvent.8
@@ -13,17 +13,21 @@
.\"
.\" 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 22, 2014" "DIREVENT" "Direvent User Reference"
+.TH DIREVENT 8 "September 1, 2014" "DIREVENT" "Direvent User Reference"
.SH NAME
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]\
+ [\fB-T\fR \fICOMMAND\fR]\
+ [\fB\-\-debug\fR]\
+ [\fB\-\-facility\fR=\fINAME\fR]\
[\fB\-\-foreground\fB]\
- [\fB\-\-pidfile\fR=\fIFILE\fR] [\fBCONFIG\fR]
+ [\fB\-\-pidfile\fR=\fIFILE\fR]\
+ [\fB\-\-self\-test\fR=\fICOMMAND\fR]\
+ [\fB\-\-user\fR=\fINAME\fR]\
+ [\fBCONFIG\fR]
.B direvent \-h
.br
@@ -97,9 +101,6 @@ section above).
.BR \-d ", " \-\-debug
Increase debug verbosity level.
.TP
-.BR \-f ", " \-\-foreground
-Run in the foreground.
-.TP
\fB\-F\fR, \fB\-\-facility=\fIFACILITY\fR
Log under this syslog facility. Allowed values for \fIFACILITY\fR are
a decimal number or any of the following symbolic names:
@@ -118,11 +119,8 @@ and
The option \fB\-F 0\fR directs logging to the standard error.
.TP
-\fB\-P\fR, \fB\-\-pidfile=\fIFILE\fR
-Write PID to \fIFILE\fR.
-.TP
-.BR \-t ", " \-\-lint
-Check configuration file for errors and exit.
+.BR \-f ", " \-\-foreground
+Run in the foreground.
.TP
\fB\-l\fR \fIPRIO\fR
While connected to a terminal \fBdirevent\fR outputs its diagnostics
@@ -141,8 +139,37 @@ severity):
When this option is given, only messages with the priority level equal
to or greater than \fIPRIO\fR will be duplicated on the standard error.
.TP
+\fB\-P\fR, \fB\-\-pidfile=\fIFILE\fR
+Write PID to \fIFILE\fR.
+.TP
+\fB\-T\fR, \fB\-\-self\-test=\fICOMMAND\fR
+Run in \fIself-test mode\fR. In this mode, \fBdirevent\fR starts
+external command supplied as the argument to this option and continues
+running until the command exits. If the command terminates normally,
+\fBdirevent\fR exits with the code returned by it. If the command
+terminates on \fBSIGHUP\fR, \fBdirevent\fR exits with code 0. If it
+terminates on another signal, \fBdirevent\fR exits with code 2.
+
+\fICOMMAND\fR can include any command line options or arguments,
+provided that it is properly quoted. It is invoked as
+.BI "/bin/sh -c " COMMAND
+in the environment of the parent \fBdirevent\fR process.
+
+The macro variable
+.B $self_test_pid
+holds the PID of the \fICOMMAND\fR (see section
+.B MACRO EXPANSION
+in
+.BR direvent.conf (5)).
+.TP
+.BR \-t ", " \-\-lint
+Check configuration file for errors and exit.
+.TP
\fB\-u\fR, \fB\-\-user=\fIUSER\fR
Run as this \fIUSER\fR.
+.PP
+Informative options cause the program to display the requested piece
+of information and exit:
.TP
.BR \-h ", " \-\-help
Output a terse help summary and exit.
diff --git a/doc/direvent.conf.5 b/doc/direvent.conf.5
index 023cd6f..c5bd895 100644
--- a/doc/direvent.conf.5
+++ b/doc/direvent.conf.5
@@ -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.CONF 5 "August 10, 2014" "DIREVENT" "Direvent User Reference"
+.TH DIREVENT.CONF 5 "September 1, 2014" "DIREVENT" "Direvent User Reference"
direvent.conf \- configuration file for
.BR direvent (8).
.SH DESCRIPTION
@@ -286,6 +286,22 @@ The following macros are defined:
.B file
Name of the file covered by the event.
.TP
+.B genev_code
+Generic (system-independent) event code. It is a bitwise \fBOR\fR of
+the event codes represented as a decimal number.
+.TP
+.B 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 \fBgenev_code\fR.
+.TP
+.B self_test_pid
+The PID of the external command started with the
+.BR \-\-self\-test " (" \-T )
+option. If
+.B direvent
+is started without this option, this variable is not defined.
+.TP
.B sysev_code
System-dependent event code. It is a bitwise \fBOR\fR of the event codes
represented as a decimal number.
@@ -299,15 +315,6 @@ the section
in
.BR direvent (8),
for a list of system-dependent event names.
-.TP
-.B genev_code
-Generic (system-independent) event code. It is a bitwise \fBOR\fR of
-the event codes represented as a decimal number.
-.TP
-.B 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 \fBgenev_code\fR.
.SH GENERAL SETTINGS
.TP
\fBuser\fR \fINAME\fR;
diff --git a/doc/direvent.texi b/doc/direvent.texi
index 104ced0..6a1bd97 100644
--- a/doc/direvent.texi
+++ b/doc/direvent.texi
@@ -144,6 +144,7 @@ File attributes have changed. This includes changes in the file
ownership, mode, link count, etc.
@end table
+@anchor{handler}
@cindex watcher, introduced
@cindex handler, introduced
A @dfn{watcher} is a configuration entity that associates a set of
@@ -313,22 +314,16 @@ of the default @file{/etc/direvent.conf}.
The options are:
@table @option
-@opindex -F
-@opindex --facility
-@item -F @var{name}
-@itemx --facility=@var{name}
-Set syslog facility.
-@opindex -P
-@opindex --pidfile
-@item -P @var{file}
-@itemx --pidfile=@var{file}
-Upon successful startup store the PID of the daemon process in
-@var{file}.
@opindex -d
@opindex --debug
@item -d
@itemx --debug
Increase debug level.
+@opindex -F
+@opindex --facility
+@item -F @var{name}
+@itemx --facility=@var{name}
+Set syslog facility.
@opindex -f
@opindex --foreground
@item -f
@@ -344,6 +339,69 @@ 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 error.
+@opindex -P
+@opindex --pidfile
+@item -P @var{file}
+@itemx --pidfile=@var{file}
+Upon successful startup store the PID of the daemon process in
+@var{file}.
+@opindex -T
+@opindex --self-test
+@cindex self-test mode
+@anchor{self-test mode}
+@item -T @var{command}
+@itemx --self-test=@var{command}
+Run in @dfn{self-test mode}. In this mode, @command{direvent} starts
+external command supplied as the argument to this option and continues
+running until the command exits. If @var{command} terminates normally,
+@command{direvent} exits with the code returned by it. If
+@var{command} terminates on signal, @command{direvent} exits with
+code @samp{0} if this signal was @code{SIGHUP}, and with code @samp{2}
+otherwise.
+
+The @var{command} can include any command line options or arguments,
+provided that it is properly quoted. It is invoked as
+@command{/bin/sh -c @var{command}} in the environment of
+the parent @command{direvent} process.
+
+This mode is used in @command{direvent} test suite. The idea is
+to configure the handler (@pxref{handler}) so that it sends
+@code{SIGHUP} to @var{command} before exiting. To this effect,
+the special macro variable @code{$self_test_pid} is
+defined (@pxref{macro expansion}) to the PID of the running
+@var{command} process. For example, consider configuration file
+@file{test.conf}, which contains the following:
+
+@example
+watcher @{
+ path /tmp;
+ command "/bin/kill -HUP $self_test_pid";
+@}
+@end example
+
+Then, the following command can be used to check whether
+@command{direvent} correctly reacts on file creation in
+the watched directory:
+
+@example
+$ direvent --foreground \
+ --self-test 'touch /tmp/file && /usr/bin/sleep 20 && exit 1' \
+ test.conf
+@end example
+
+The command will return @samp{0} if the handler was invoked, and @samp{1}
+if it was not.
+@opindex -t
+@opindex --lint
+@item -t
+@itemx --lint
+Check configuration file for errors and exit.
+@opindex -u
+@opindex --user
+@item -u @var{name}
+@itemx --user=@var{name}
+Run as this user. This option overrides the @code{user} configuration
+statement (@pxref{general settings, user}).
@end table
The following options are @dfn{informative}. They cause the program
@@ -355,18 +413,19 @@ to display the requested piece of information and terminate:
@item -H
@itemx --config-help
Show configuration file summary.
-@opindex -V
-@opindex --version
-@item -V
-@itemx --version
-Print program version.
@opindex -h
@opindex --help
@item -h
@itemx --help
Give a short usage summary.
+@opindex --usage
@item --usage
Display available command line options.
+@opindex -V
+@opindex --version
+@item -V
+@itemx --version
+Print program version.
@end table
@node Configuration
@@ -644,9 +703,9 @@ this is not required.
@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. Curly braces around the @var{name} are optional.
+by the value of the macro variable @var{name}. Variable names follow
+the usual convention: they begin with a letter and contain letters,
+digits and 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}.
@@ -659,6 +718,25 @@ The following macros are defined:
@item file
Name of the file that triggered the event.
+@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}.
+
+@kwindex self_test_pid
+@item self_test_pid
+The PID of the external command started with the @option{--self-test}
+option (@pxref{self-test mode}). If @command{direvent} is started
+without this option, this variable is not defined.
+
@anchor{$sysev_code}
@kwindex sysev_code, macro variable
@item sysev_code
@@ -672,19 +750,6 @@ 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
@node general settings
diff --git a/src/cmdline.opt b/src/cmdline.opt
index 5d6eafe..b7e1dd7 100644
--- a/src/cmdline.opt
+++ b/src/cmdline.opt
@@ -46,13 +46,13 @@ BEGIN
opt_pidfile = optarg;
END
-OPTION(lint,t,,,
+OPTION(lint,t,,
[<check configuration file and exit>])
BEGIN
lint_only = 1;
END
-OPTION(user,u,USER,,
+OPTION(user,u,USER,
[<run as this user>])
BEGIN
opt_user = optarg;
diff --git a/src/direvent.c b/src/direvent.c
index 5840f2e..aa0e2f3 100644
--- a/src/direvent.c
+++ b/src/direvent.c
@@ -404,22 +404,13 @@ sigmain(int sig)
stop = 1;
}
}
-extern char **environ;
void
self_test()
{
pid_t pid;
- struct wordsplit ws;
-
- ws.ws_env = (const char **)environ;
- if (wordsplit(self_test_prog, &ws,
- WRDSF_NOCMD | WRDSF_QUOTE | WRDSF_SQUEEZE_DELIMS |
- WRDSF_CESCAPES | WRDSF_ENV)) {
- diag(LOG_CRIT, "wordsplit: %s", wordsplit_strerror (&ws));
- exit(2);
- }
-
+ char *args[4];
+
pid = fork();
if (pid == (pid_t)-1) {
diag(LOG_CRIT,
@@ -432,10 +423,14 @@ self_test()
self_test_pid = pid;
return;
}
-
- execv(ws.ws_wordv[0], ws.ws_wordv);
- diag(LOG_ERR, "execv: %s: %s", ws.ws_wordv[0], strerror(errno));
+ args[0] = "/bin/sh";
+ args[1] = "-c";
+ args[2] = self_test_prog;
+ args[3] = NULL;
+ execv(args[0], args);
+
+ diag(LOG_ERR, "execv: %s: %s", self_test_prog, strerror(errno));
_exit(127);
}

Return to:

Send suggestions and report system problems to the System administrator.