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.

3 files changed, 153 insertions, 54 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