diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-06-02 14:09:07 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-06-02 14:09:07 +0300 |
commit | ca9b31699add4e77bdf12299e8c58d7f5ee05e54 (patch) | |
tree | b072d9699a0dc8f32143a19928abc9145814b3ad | |
parent | d5cb78fee98415db80c1c89ec097f14c298968f4 (diff) | |
download | direvent-ca9b31699add4e77bdf12299e8c58d7f5ee05e54.tar.gz direvent-ca9b31699add4e77bdf12299e8c58d7f5ee05e54.tar.bz2 |
Write the docs in manpage format:
* doc/.gitignore
* doc/Makefile.am: Add rules for texinfo documents.
* doc/dircond.1: Removed.
* doc/dircond.8: New file.
* doc/dircond.conf.5: New file.
* doc/dircond.texi: New file (a placeholder).
* doc/fdl.texi: New file.
* doc/gendocs_template: New file.
Rename event variables and the corresponding environment
ones:
* src/environ.c
* src/dircond.c
* src/progman.c
* tests/.gitignore
* tests/attrib.at
* tests/cmdexp.at
* tests/create.at
* tests/delete.at
* tests/env00.at
* tests/env01.at
* tests/env03.at
* tests/remove.at
* tests/write.at
-rw-r--r-- | doc/.gitignore | 23 | ||||
-rw-r--r-- | doc/Makefile.am | 29 | ||||
-rw-r--r-- | doc/dircond.1 | 318 | ||||
-rw-r--r-- | doc/dircond.8 | 453 | ||||
-rw-r--r-- | doc/dircond.conf.5 | 575 | ||||
-rw-r--r-- | doc/dircond.texi | 129 | ||||
-rw-r--r-- | doc/fdl.texi | 449 | ||||
-rwxr-xr-x | doc/gendocs_template | 78 | ||||
-rw-r--r-- | src/dircond.c | 2 | ||||
-rw-r--r-- | src/environ.c | 8 | ||||
-rw-r--r-- | src/progman.c | 8 | ||||
-rw-r--r-- | tests/.gitignore | 4 | ||||
-rw-r--r-- | tests/attrib.at | 8 | ||||
-rw-r--r-- | tests/cmdexp.at | 8 | ||||
-rw-r--r-- | tests/create.at | 8 | ||||
-rw-r--r-- | tests/delete.at | 8 | ||||
-rw-r--r-- | tests/env00.at | 8 | ||||
-rw-r--r-- | tests/env01.at | 8 | ||||
-rw-r--r-- | tests/env03.at | 2 | ||||
-rw-r--r-- | tests/remove.at | 4 | ||||
-rw-r--r-- | tests/write.at | 8 |
21 files changed, 1777 insertions, 361 deletions
diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..893d222 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,23 @@ +Makefile +Makefile.in +dircond.info* +stamp-vti +version.texi +dircond.aux +dircond.cp +dircond.cps +dircond.dvi +dircond.fl +dircond.fn +dircond.kw +dircond.ky +dircond.log +dircond.mt +dircond.op +dircond.pg +dircond.pr +dircond.ps +dircond.toc +dircond.tp +dircond.vr +manual diff --git a/doc/Makefile.am b/doc/Makefile.am index af4c4f9..9b12828 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1 +1,28 @@ -dist_man_MANS=dircond.1 +info_TEXINFOS=dircond.texi +dircond_TEXINFOS=\ + fdl.texi + +dist_man_MANS=dircond.8 dircond.conf.5 + +EXTRA_DIST = \ + gendocs_template + +clean-local: + @rm -rf manual + +GENDOCS=gendocs.sh + +TEXI2DVI=texi2dvi -t '@set $(RENDITION)' -E + +.PHONY: manual +manual: + TEXINPUTS=$(srcdir):$(top_srcdir)/build-aux:$(TEXINPUTS) \ + MAKEINFO="$(MAKEINFO) $(MAKEINFOFLAGS) $(AM_MAKEINFOFLAGS)" \ + TEXI2DVI="$(TEXI2DVI)" \ + TEXI2HTML="texi2html $(AM_MAKEINFOFLAGS)" \ + $(GENDOCS) --texi2html $(PACKAGE) '$(PACKAGE_NAME) manual' + +manual.tar.bz2: manual + tar cfj manual.tar.bz2 manual + +man-tar: manual.tar.bz2 diff --git a/doc/dircond.1 b/doc/dircond.1 deleted file mode 100644 index 7055582..0000000 --- a/doc/dircond.1 +++ /dev/null @@ -1,318 +0,0 @@ -.\" dircond - directory content watcher daemon -*- nroff -*- -.\" Copyright (C) 2012, 2013 Sergey Poznyakoff -.\" -.\" Dircond is free software; you can redistribute it and/or modify it -.\" under the terms of the GNU General Public License as published by the -.\" Free Software Foundation; either version 3 of the License, or (at your -.\" option) any later version. -.\" -.\" Dircond is distributed in the hope that it will be useful, -.\" 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 dircond. If not, see <http://www.gnu.org/licenses/>. -.TH DIRCOND 1 "March 8, 2013" "DIRCOND" "Dircond User Reference" -.SH NAME -dircond \- directory content watcher -.SH SYNOPSIS -\fBdircond\fR [\fB\-dft\fR] [\fB\-F\fR \fIFACILITY\fR] [\fB\-L\fR \fITAG\fR]\ - [\fB\-P\fR \fIFILE\fR]\ - [\fB\-u\fR \fIUSER\fR]\ - [\fICONFIG\fR] - -.B dircond -h - -.B dircond -V -.SH DESCRIPTION -.B Dircond -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. -.PP -The following events can be monitored by the program: -.TP -.B access -A file was accessed. -.TP -.B attrib -A file's metadata changed. -.TP -.B close_write -A writable file was closed. -.TP -.B close_nowrite -An unwritable file closed. -.TP -.B create -A file was created. -.TP -.B delete -A file was deleted. -.TP -.B modify -A file was modified. -.TP -.B moved_from -A file was moved into a monitored directory. -.TP -.B moved_to -A file was moved out from a monitored directory. -.TP -.B open -A file was opened. -.PP -When an event has been detected, -.B dircond -invokes the handler configured for it. The handler is invoked in the -directory where the event occured. Additional information about the -event is passed in the following environment variables: -.TP -.B DIRCOND_EVENT -Event symbolic name (see the event table above). -.TP -.B DIRCOND_EVENT_CODE -Event code as obtained from -.BR inotify (8). -.TP -.B DIRCOND_FILE -The name of the affected file. -.PP -Apart from these variables, the -handler environment is inherited from the calling process. If you need -to restrict the environment, start -.B dircond -via -.BR env (1). -.SH OPTIONS -.TP -.B \-d -Increase debug verbosity level. -.TP -.B \-f -Run in the foreground. -.TP -\fB\-F\fR \fIFACILITY\fR -Log under this syslog facility. Allowed values for \fIFACILITY\fR are -a decimal number or any of the following symbolic names: -.BR auth , -.BR authpriv , -.BR cron , -.BR daemon , -.BR ftp , -.BR local0 " through " local7 , -.BR lpr , -.BR mail , -.BR news , -.BR user , -and -.BR uucp . - -The option \fB\-F 0\fR directs logging to the standard error. -.TP -\fB\-L\fR \fITAG\fR -Log with this syslog tag. -.TP -\fB\-P\fR \fIFILE\fR -Write PID to \fIFILE\fR. -.TP -\fB\-t\fR -Check configuration file for errors and exit. -.TP -\fB\-u\fR \fIUSER\fR -Run as this \fIUSER\fR. -.TP -\fB\-h\fR -Output a terse help summary and exit. -.TP -\fB\-V\fR -Print program version and copyright information. -.SH CONFIGURATION -The default configuration file is -.BR /etc/dircond.conf . -If a file name is supplied as an argument to the program, that file -will be read instead. -.PP -The configuration file has the traditional line-oriented format. Very -long lines can be split into several physical lines by ending each of -them with a backslash immediately followed by a newline character. -.PP -Comments are introduced with a sharp sign and extend to the end of -logical line. -.PP -Empty lines are ignored. -.SS Global settings -.TP -\fBforeground\fR [\fBon\fR|\fBoff\fR] -Remain in foreground (if \fBon\fR or no argument given), or detach -from the controlling terminal and become a daemon (if \fBoff\fR). -The latter is the default. See also the \fB\-f\fR option. -.TP -\fBdebug\fR \fIN\fR -Set debugging level. See also the \fB\-d\fR option. -.TP -\fBpidfile\fR \fIFILE\fR -Store PID of the started process in \fIFILE\fR. See also the -\fB\-P\fR option. -.TP -\fBuser\fR \fINAME\fR -Run as user \fINAME\fR. See also the \fB\-u\fR option. -.SS Logging -The \fBsyslog\fR statement configures where the log output goes. By -default, the program logs to standard error until it finishes parsing -the configuration file and processing command line options. From then -on it begins logging to syslog with the facility \fBdaemon\fR. The -syslog settings can be altered using this statement. -.TP -.B syslog off -Disable syslog output, log everything to standard error instead. This -setting has effect only when running in the foreground. -.TP -\fBsyslog facility\fR \fIFNAME\fR -Log to syslog facility \fIFNAME\fR. The latter can be either -a decimal number or any of the following symbolic names: -.BR auth , -.BR authpriv , -.BR cron , -.BR daemon , -.BR ftp , -.BR local0 " through " local7 , -.BR lpr , -.BR mail , -.BR news , -.BR user , -and -.BR uucp . -.TP -\fBsyslog tag\fR \fISTRING\fR -Log with the given syslog tag. -.SS Handler options -Handler options affect all event handlers defined in the \fBonevent\fR -statements appearing below them. -.TP -\fBoption capture\fR \fIstream\fR [\fIenable\fR] -Capture the output stream of a handler. The \fIstream\fR parameter -specifies which stream to capture. Its possible values are: -\fBstdout\fR for the standard output, \fBstderr\fR for the standard -error, or \fBboth\fR for both streams. Optional \fIenable\fR -parameter can be \fBon\fR to enable capturing and \fBoff\fR to disable -it. - -When logging to syslog, the data read from the captured -.B stdout -will be logged with the priority -.BR LOG_INFO , -and -.B stderr -will be logged with the priority -.BR LOG_ERROR . -.TP -\fBoption wait\fR -Wait for the handler to terminate before handling subsequent events. -This is the default. -.TP -\fBoption nowait\fR -Do not wait for the handler to terminate. Start it in the background -and continue processing requests. -.TP -\fBoption timeout\fR \fIN\fR -Sets timeout in seconds for handler runtime. The default value is 5 -seconds. Note, that the timeout setting affects both \fBwait\fR and -\fBnowait\fR handlers, i.e. any handler that runs longer -than \fIN\fR seconds will be terminated by -.B SIGKILL. -.SS Event handling -.TP -\fBevent\fR \fINAME\fR \fIEVENT-ID\fR [\fIEVENT-ID\fR...] -Add listed events to the event set \fINAME\fR, creating it if it does -not exist. Each \fIEVENT-ID\fR is either a predefined event name (see -the \fBDESCRIPTION\fR section) or a \fINAME\fR of an event -set defined in a previous -.B event -statement. -.TP -\fBpath\fR \fINAME\fR \fIDIR\fR [\fBrecursive\fR [\fIN\fR]] -Add directory \fIDIR\fR to the pathset \fINAME\fR. If \fBrecursive\fR -is specified, all directories below \fIDIR\fR are also added to the -pathset. If \fBrecursive\fR is followed by a decimal number \fIN\fR, -recursive inclusion is limited to directories located no deeper than -\fIN\fR levels of nesting. -.TP -\fBonevent\fR \fIEVENT-ID\fR \fBin\fR \fIPATH-NAME\fR \fBrun\fR \fICOMMAND\fR\ - [\fBas\fR \fIUSER\fR] -Configures the handler for events occurring in the given pathset. -\fICOMMAND\fR is the full pathname of an external program. This -program will be started when one of the events from \fIEVENT-ID\fR -occur for any file in directories comprising the pathset \fIPATH-NAME\fR. -If the optional \fBas\fR \fIUSER\fR clause is supplied, the program -will be run with the UID and (main and supplementary) GIDs of \fIUSER\fR. -The latter must be either a valid user name or a numeric UID of an -existing user. -.SH EXAMPLE -.sp -.nf -.in +2 -# Store the PID of the master process in this file: -pidfile /var/run/dircond.pid - -# Log using syslog facility \fBlocal0\fR. -syslog facility local0 - -# Define event set \fBupdate\fR to match any modifications -# of file contents. -event update modify close_write moved_to - -# Define event set \fBremove\fR to cover removal of a file -# from the watched directory. -event remove delete moved_from - -# Add \fB/etc\fR and its subdirectories to pathset \fBconfigs\fR. -path configs /etc recursive - -# Don't allow event handler to run longer than 10 seconds. -option timeout 10 -# Capture both standard output and error and divert them -# to the log file. -option capture both - -# If any file gets updated in \fB/etc\fR or any of its -# subdirectories, call the program \fB/usr/bin/confchange\fR. -onevent update in configs run /usr/bin/confchange as daemon - -# Another handler, for removals in the configuration directory. -onevent delete in configs run /usr/bin/confdel -.in -.fi -.SH "EXIT CODE" -.IP 0 -Successful termination. -.IP 1 -Command line usage error. -.IP 2 -Another error occurred. -.SH "SEE ALSO" -.BR inotify (8). -.SH AUTHORS -Sergey Poznyakoff -.SH "BUG REPORTS" -Report bugs to <gray+dircond@gnu.org.ua>. -.SH COPYRIGHT -Copyright \(co 2012, 2013 Sergey Poznyakoff -.br -.na -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -.ad -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.\" Local variables: -.\" eval: (add-hook 'write-file-hooks 'time-stamp) -.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \"" -.\" time-stamp-format: "%:B %:d, %:y" -.\" time-stamp-end: "\"" -.\" time-stamp-line-limit: 20 -.\" end: - diff --git a/doc/dircond.8 b/doc/dircond.8 new file mode 100644 index 0000000..4b9a96b --- /dev/null +++ b/doc/dircond.8 @@ -0,0 +1,453 @@ +.\" dircond - directory content watcher daemon -*- nroff -*- +.\" Copyright (C) 2012, 2013 Sergey Poznyakoff +.\" +.\" Dircond is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 3 of the License, or (at your +.\" option) any later version. +.\" +.\" Dircond is distributed in the hope that it will be useful, +.\" 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 dircond. If not, see <http://www.gnu.org/licenses/>. +.TH DIRCOND 1 "June 2, 2013" "DIRCOND" "Dircond User Reference" +.SH NAME +dircond \- directory content watcher +.SH SYNOPSIS +\fBdircond\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\-\-foreground\fB]\ + [\fB\-\-pidfile\fR=\fIFILE\fR] [\fBCONFIG\fR] + +.B dircond \-h +.br +.B dircond \-\-help + +.B dircond \-H +.br +.B dircond \-\-config\-help + +.B dircond \-\-usage + +.B dircond \-V +.br +.B dircond \-\-version + +.SH DESCRIPTION +.B Dircond +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. +.PP +The following +.B generic +events can be monitored by the program: +.TP +.B create +A file was created; +.TP +.B delete +A file was deleted; +.TP +.B write +A file was written to; +.TP +.B attrib +File attributes have changed. This includes changes in the file +ownership, mode, link count, etc. +.PP +Depending on the interface provided by the underlying operating system +.B dircond +can trace various +.B system-dependent +events, which may offer a better resolution. These events are +described in the section +.B SYSTEM DEPENDENCIES +below. +.PP +A +.B watcher +is a configuration entity within +.B dircond +which associates a set of directories with a set of events and +instructs the program to run a specified external command when +any of these events occur in any of these directories. This +external command (called a \fBhandler\fR) can obtain information +about the event that triggered its execution from the environment +variables, or from its command line (see the \fBHANDLER ENVIRONMENT\fR +section below). +.PP +Watchers are declared in the program configuration file +.BR dircond.conf , +located in the system configuration directory (normally \fB/etc\fR). +.PP +An alternative configuration file can be used, by supplying its pathname +as the command line argument (\fICONFIG\fR parameter in the \fBSYNOPSIS\fR +section above). +.SH OPTIONS +.TP +.BR \-\-debug ", " \-d +Increase debug verbosity level. +.TP +.BR \-\-foreground ", " \-f +Run in the foreground. +.TP +\fB\-\-facility\fR, \fB\-F\fR \fIFACILITY\fR +Log under this syslog facility. Allowed values for \fIFACILITY\fR are +a decimal number or any of the following symbolic names: +.BR auth , +.BR authpriv , +.BR cron , +.BR daemon , +.BR ftp , +.BR local0 " through " local7 , +.BR lpr , +.BR mail , +.BR news , +.BR user , +and +.BR uucp . + +The option \fB\-F 0\fR directs logging to the standard error. +.TP +\fB\-\-pidfile\fR, \fB\-P\fR \fIFILE\fR +Write PID to \fIFILE\fR. +.TP +.BR \-\-lint ", " \-t +Check configuration file for errors and exit. +.TP +\fB\-l\fR \fIPRIO\fR +While connected to a terminal \fBdircond\fR outputs its diagnostics +messages to stderr and, if configured, to \fBsyslog\fR. This option +limits the amount of information output to the standard error. +\fIPRIO\fR is one of the following priorities (in order of increasing +severity): +.BR debug , +.BR info , +.BR notice , +.BR warning , +.BR err , +.BR crit , +.BR alert , +.BR emerg . +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\-\-user\fR, \fB\-u\fR \fIUSER\fR +Run as this \fIUSER\fR. +.TP +.BR \-\-help ", " \-h +Output a terse help summary and exit. +.TP +.BR \-\-config\-help ", " \-H +Describe configuration file syntax. +.TP +.B \-\-usage +Show available command line options. +.TP +.BR \-\-version ", " \-V +Print program version and copyright information. +.SH CONFIGURATION +The default configuration file is +.BR /etc/dircond.conf . +If a file name is supplied as an argument to the program, that file +will be read instead. +.PP +The configuration file syntax is discussed in detail in +.BR dircond.conf (5). +This section provides only a short description of it. +.PP +Three types of comments are allowed: inline comments, that begin with +a \fB#\fR or \fB//\fR and extend to the end of line, and multi-line +comments, which comprise everything enclosed between \fB/*\fR and +\fB*/\fR. Comments and empty lines are ignored. Whitespace +characters are ignored as well, except as they serve to separate +tokens. +.PP +A token is a string of consecutive characters from the following +classes: alphanumeric characters, underscores, dots, asteriscs, +slashes, semicolons, commercial at's, and dashes. +.PP +Any other sequence of characters must be enclosed in double quotation +marks in order to represent a single token. +.PP +Adjacent quoted strings are concatenated. +.PP +Configuration statements consist 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. +.PP +The most important configuration statement is +.BR watcher . +It is defined as follows: +.sp +.nf +.in +2 +.B watcher { +.in +4 +\fBpath\fR \fIPATHNAME\fR [\fBrecursive\fR [\fILEVEL\fR]]; +.BI "event " EVENT\-LIST ; +.BI "command " COMMAND\-LINE ; +.BI "user " NAME ; +.BI "timeout " NUMBER ; +.BI "environ " ENV\-SPEC ; +.BI "option " STRING\-LIST ; +.in -4 +.B } +.in +.fi +.PP +Each \fBwatcher\fR statement instructs \fBdircond\fR to monitor +the events listed in \fIEVENT\-LIST\fR occurring in the directories +specified by \fIPATHNAME\fRs in \fBpath\fR statements (any number of +\fBpath\fR statements can be given). When any such event is detected, +the \fICOMMAND\-LINE\fR will be executed. +.PP +Each directory defined with the \fBrecursive\fR keyword will be +watched recursively. This means that for each subdirectory created in +it, \fBdircond\fR will install a watcher similar to that of its parent +directory. The optional \fILEVEL\fR can be used to set-up a cut-off +nesting level, beyond which the recursive operation is disabled. +.PP +The rest of statements are optional. The \fBuser\fR statement can be +used to execute the \fICOMMAND\-LINE\fR as a user \fINAME\fR +(provided, of course, that \fBdircond\fR is started with root +privileges). The \fBtimeout\fR specifies the maximum amount of time +(in seconds) the command is allowed to run. It defaults to 5. The +\fBenviron\fR statements modifies the command environment (see the +following section). Finally, the \fBoption\fR statement supplies +additional options. It can be used, for example, to divert the +command's output to \fBsyslog\fR. +.PP +The program's logging is controlled by the \fBdebug\fR and +\fBsyslog\fR statements. +.TP +.BI "debug " NUMBER ; +Sets the debugging level to \fINUMBER\fR -- an integer value between 0 +and 3. Zero is the default and means the debugging is disabled. The +bigger the \fINUMBER\fR the more detailed debugging information will +be output. +.PP +The \fBsyslog\fR statement controls the syslog logging: +.sp +.nf +.in +2 +.B syslog { +.in +4 +.BI "facility " STRING ; +.BI "tag " STRING ; +.BI "print\-priority " BOOL ; +.in -4 +.B } +.PP +The \fBpidfile\fR statement instructs the program to write its PID to +the named file after disconnecting from the controlling terminal. +.SH "HANDLER ENVIRONMENT" +The handler to be executed on an event is defined by the \fBcommand\fR +statement in the \fBwatcher\fR configuration block (see +.BR dircond.conf (5)). +Before executing, the following operations are performed: +.nr step 1 1 +.IP \n[step]. +The current working directory is set to the directory where the event +occurred. +.IP \n+[step]. +If the \fBenviron\fR statement is present in the watcher, the +environment is modified according to its rules. See the description +of the \fBenviron\fR statement in +.BR dircond.conf (5). +.IP \n+[step]. +The standard input is closed. +.IP +If the \fBstdout\fR option is supplied, +the standard output is captured and redirected to the \fBsyslog\fR. +Otherwise it is closed. +.IP +If the \fBstderr\fR option is supplied, +the standard error is captured and redirected to the \fBsyslog\fR. +Otherwise it is closed. +.IP +All file descriptors above 2 are closed. +.IP \n+[step]. +\fBMacro variables\fR are expanded. See the section +.B MACRO EXPANSION +in +.BR dircond.conf (5). +For example, if the handler is about to be executed for the +\fBwrite\fR event on the file \fBsomefile\fR, and the \fBcommand\fR +definition was: +.RS +.sp +.nf +.in +4 +command "/libexec/handler -e '$genev_name' -f '$file'"; +.in +.fi +.RE +.IP +then the resulting command line will be: +.RS +.sp +.nf +.in +4 +/libexec/handler -e 'open' -f 'somefile' +.in +.fi +.RE +.IP \n+[step]. +Word splitting is performed on the resulting command line. The first +word is treated as the pathname of the program to be executed. +.IP \n+[step]. +The program is invoked. +.SH "SYSTEM DEPENDENCIES" +\fBDircond\fR relies on the event monitoring API provided by the +kernel. +.SH Linux +On \fBLinux\fR the program uses +.BR inotify (8). +.PP +The maximum number of watches a user process can have is controlled by +the +.B fs.inotify.max_user_watches +system variable. Normally it is set to 8192, which is quite enough +for most purposes. However, if you monitor a big number or +directories and/or are using recursive watchers, you may need more +watches. In that case, use +.BR sysctl (8) +to raise the limit, e.g.: +.sp +.nf +.in +4 +sysctl -w fs.inotify.max_user_watches=16384 +.in +.fi +.PP +Most GNU/Linux distributions provide the file +.B /etc/sysctl.conf +which can be used to set this variable on startup. +.PP +The following system-dependent events are defined on systems that use +.BR inotify (8): +.TP +.B ACCESS +A file was accessed. +.TP +.B ATTRIB +A file's metadata changed. +.TP +.B CLOSE_WRITE +A writable file was closed. +.TP +.B CLOSE_NOWRITE +An unwritable file closed. +.TP +.B CREATE +A file was created. +.TP +.B DELETE +A file was deleted. +.TP +.B MODIFY +A file was modified. +.TP +.B MOVED_FROM +A file was moved into a monitored directory. +.TP +.B MOVED_TO +A file was moved out from a monitored directory. +.TP +.B OPEN +A file was opened. +.SH BSD +When compiled on \fBBSD\fR systems (including \fBDarwin\fR), +\fBdircond\fR uses +.BR kqueue (2). +This interface needs an open file handle for each file in a monitored +directory, which means that the number of watchers is limited by the +maximum number of open files. Use +.BI "ulimit -n " NUM +to raise it to a higher number. +.PP +Since it operates on files, \fBkqueue\fR does not provide direct +support for the \fBcreate\fR generic event. \fBDircond\fR works +over this disadvantage by keeping track of the contents of each +monitored directory and rescanning it each time a \fBWRITE\fR system +event is reported for it. It then generates the +\fBopen\fR event for each file that appeared after the last scan. +Such a rescan can consume considerable time if a directory has a very +large number of files in it. +.PP +The following system-dependent events are available: +.TP +.B DELETE +The \fBunlink()\fR system call was called on the monitored file. +.TP +.B WRITE +A write occurred on the file. +.TP +.B EXTEND +The file was extended. +.TP +.B ATTRIB +The file attributes have changed. +.TP +.B LINK +The link count on the file changed. +.TP +.B RENAME +The file was renamed. +.TP +.B REVOKE +Access to the file was revoked via +.BR revoke (2) +or the underlying file system was unmounted. +.SH Darwin +Essentially the same as +.BR BSD . +The main difference compared to \fBLinux\fR and \fBBSD\fR is that on +\fBDarwin\fR the watchers are set after disconnecting from the +controlling terminal, which means that any errors which may happen +during this process are directed to the syslog instead of the standard +error. This is because \fBDarwin\fR lacks the +.BR rfork (2) +call and the event queue cannot be inherited by the child process. +.SH "EXIT CODE" +.IP 0 +Successful termination. +.IP 1 +Command line usage error. +.IP 2 +Another error occurred. +.SH "SEE ALSO" +.BR dircond.conf (5), +.BR inotify (8), +.BR kqueue (2). +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to <gray+dircond@gnu.org.ua>. +.SH COPYRIGHT +Copyright \(co 2012, 2013 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> +.br +.ad +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.\" Local variables: +.\" eval: (add-hook 'write-file-hooks 'time-stamp) +.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \"" +.\" time-stamp-format: "%:B %:d, %:y" +.\" time-stamp-end: "\"" +.\" time-stamp-line-limit: 20 +.\" end: + diff --git a/doc/dircond.conf.5 b/doc/dircond.conf.5 new file mode 100644 index 0000000..1b09a1d --- /dev/null +++ b/doc/dircond.conf.5 @@ -0,0 +1,575 @@ +.\" dircond - directory content watcher daemon -*- nroff -*- +.\" Copyright (C) 2012, 2013 Sergey Poznyakoff +.\" +.\" Dircond is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 3 of the License, or (at your +.\" option) any later version. +.\" +.\" Dircond is distributed in the hope that it will be useful, +.\" 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 dircond. If not, see <http://www.gnu.org/licenses/>. +.TH DIRCOND.CONF 5 "June 2, 2013" "DIRCOND" "Dircond User Reference" +dircond.conf \- configuration file for +.BR dircond (8). +.SH DESCRIPTION +The configuration file consists of statements and comments. +.PP +There are three classes of lexical tokens: keywords, values, and +separators. Blanks, tabs, newlines and comments, collectively called +\fIwhite space\fR are ignored except as they serve to separate +tokens. Some white space is required to separate otherwise adjacent +keywords and values. +.SH COMMENTS +Comments may appear anywhere where white space may appear in the +configuration file. There are two kinds of comments: +single-line and multi-line comments. Single-line comments start +with +.B # +or +.B // +and continue to the end of the line: +.sp +.RS 4 +.nf +# This is a comment +// This too is a comment +.fi +.RE +.PP +\fIMulti-line\fB or \fIC-style\fR comments start with the two +characters +.B /* +(slash, star) and continue until the first occurrence of +.B */ +(star, slash). +.PP +Multi-line comments cannot be nested. However, single-line comments +may well appear within multi-line ones. +.SS "Pragmatic Comments" +Pragmatic comments are similar to usual single-line comments, +except that they cause some changes in the way the configuration is +parsed. Pragmatic comments begin with a +.B # +sign and end with the next physical newline character. +.TP +.BR "#include <" "file" > +.PD 0 +.TP +.BR "#include " "file" +.PD +Include the contents of the file \fIfile\fR. If it is an +absolute file name, both forms are equivalent. Otherwise, the form +with angle brackets searches for the file in the \fIinclude +search path\fR, while the second one looks for it in the current working +directory first, and, if not found there, in the include search +path. +.sp +The default include search path is: \fBFIXME\fR. +.TP +.BR "#include_once <" "file" > +.PD 0 +.TP +.BR "#include_once " "file" +.PD +Same as \fB#include\fR, except that, if the \fIfile\fR has already +been included, it will not be included again. +.TP +.BR "#line " "num" +.PD 0 +.TP +.BR "#line " "num" " \(dq" "file" "\(dq" +.PD +This line causes the parser to believe, for purposes of error +diagnostics, that the line number of the next source line +is given by \fInum\fR and the current input file is named by +\fIfile\fR. If the latter is absent, the remembered file name +does not change. +.TP +.BR "# " "num" " \(dq" "file" "\(dq" +This is a special form of the \fB#line\fR statement, understood for +compatibility with the C preprocessor. +.SH STATEMENTS +.SS "Simple statement" +A \fIsimple statement\fR consists of a keyword and value +separated by any amount of whitespace. Simple statement is terminated +with a semicolon (\fB;\fR). +.PP +The following is a simple statement: +.sp +.RS 4 +.nf +pidfile /var/run/dircond.pid; +.RE +.fi +.PP +See below for a list of valid simple statements. +.PP +A \fIvalue\fR can be one of the following: +.TP +.I number +A number is a sequence of decimal digits. +.TP +.I boolean +A boolean value is one of the following: \fByes\fR, \fBtrue\fR, +\fBt\fR or \fB1\fR, meaning \fItrue\fR, and \fBno\fR, +\fBfalse\fR, \fBnil\fR, \fB0\fR meaning \fIfalse\fR. +.TP +.I unquoted string +An unquoted string may contain letters, digits, and any of the +following characters: \fB_\fR, \fB\-\fR, \fB.\fR, \fB/\fR, +\fB@\fR, \fB*\fR, \fB:\fR. +.TP +.I quoted string +A quoted s |