diff options
-rw-r--r-- | doc/direvent.8 | 51 | ||||
-rw-r--r-- | doc/direvent.conf.5 | 27 | ||||
-rw-r--r-- | doc/direvent.texi | 129 | ||||
-rw-r--r-- | src/cmdline.opt | 4 | ||||
-rw-r--r-- | src/direvent.c | 23 |
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); } |