aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2013-06-02 14:09:07 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2013-06-02 14:09:07 +0300
commitca9b31699add4e77bdf12299e8c58d7f5ee05e54 (patch)
treeb072d9699a0dc8f32143a19928abc9145814b3ad
parentd5cb78fee98415db80c1c89ec097f14c298968f4 (diff)
downloaddirevent-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/.gitignore23
-rw-r--r--doc/Makefile.am29
-rw-r--r--doc/dircond.1318
-rw-r--r--doc/dircond.8453
-rw-r--r--doc/dircond.conf.5575
-rw-r--r--doc/dircond.texi129
-rw-r--r--doc/fdl.texi449
-rwxr-xr-xdoc/gendocs_template78
-rw-r--r--src/dircond.c2
-rw-r--r--src/environ.c8
-rw-r--r--src/progman.c8
-rw-r--r--tests/.gitignore4
-rw-r--r--tests/attrib.at8
-rw-r--r--tests/cmdexp.at8
-rw-r--r--tests/create.at8
-rw-r--r--tests/delete.at8
-rw-r--r--tests/env00.at8
-rw-r--r--tests/env01.at8
-rw-r--r--tests/env03.at2
-rw-r--r--tests/remove.at4
-rw-r--r--tests/write.at8
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