1DIREVENT(8) Direvent User Reference DIREVENT(8)
2
6 direvent - directory event monitor
7
9 direvent [-HVdfh] [-F NAME] [-P FILE] [-l PRIO] [-I DIR] [-T COMMAND]
10 [--debug] [--facility=NAME] [--foreground] [--include=DIR] [--pid‐
11 file=FILE] [--self-test=COMMAND] [--user=NAME] [CONFIG]
12 direvent -h
14 direvent --help
15 direvent -H
17 direvent --config-help
18 direvent --usage
20 direvent -V
22 direvent --version
23
26 GNU Direvent monitors a set of directories on the file system and re‐
27 acts when a file system event occurs in any of them. Directories and
28 events to monitor are specified in the configuration file. When an
29 event occurs the utility reacts by invoking an external command config‐
30 ured for that event.
31 The following generic events can be monitored by the program:
33 create A file was created;
35 delete A file was deleted;
37 write A file was written to;
39 attrib File attributes have changed. This includes changes in the file
41 ownership, mode, link count, etc.
42 Depending on the interface provided by the underlying operating system
44 direvent can trace various system-dependent events, which may offer a
45 better resolution. These events are described in the section SYSTEM
46 DEPENDENCIES below.
47 A watcher is a configuration entity within direvent which associates a
49 set of directories with a set of events and instructs the program to
50 run a specified external command when any of these events occur in any
51 of these directories. This external command (called a handler) can ob‐
52 tain information about the event that triggered its execution from the
53 environment variables, or from its command line (see the HANDLER ENVI‐
54 RONMENT section below).
55 Watchers are declared in the program configuration file direvent.conf,
57 located in the system configuration directory (normally /etc).
58 An alternative configuration file can be used, by supplying its path‐
60 name as the command line argument (CONFIG parameter in the SYNOPSIS
61 section above).
62
64 -d, --debug
65 Increase debug verbosity level.
66 -F, --facility=FACILITY
68 Log under this syslog facility. Allowed values for FACILITY are
69 a decimal number or any of the following symbolic names: auth,
70 authpriv, cron, daemon, ftp, local0 through local7, lpr, mail,
71 news, user, and uucp.
72 The option -F 0 directs logging to the standard error.
74 -f, --foreground
76 Run in the foreground.
77 -I, --include=DIR
79 Add DIR to the include search path. When looking for a file to
80 be included in the #include (#include_once) statement, direvent
81 scans first the directories given with -I options (in the same
82 order as given on the command line), and then the directories in
83 the standard include search path. The latter is defined at com‐
84 pile time and can be inspected in the output of the --help op‐
85 tion.
86 -l PRIO
88 While connected to a terminal direvent outputs its diagnostics
89 messages to stderr and, if configured, to syslog. This option
90 limits the amount of information output to the standard error.
91 PRIO is one of the following priorities (in order of increasing
92 severity): debug, info, notice, warning, err, crit, alert,
93 emerg. When this option is given, only messages with the prior‐
94 ity level equal to or greater than PRIO will be duplicated on
95 the standard error.
96 -P, --pidfile=FILE
98 Write PID to FILE.
99 -T, --self-test=COMMAND
101 Run in self-test mode. In this mode, direvent starts external
102 command supplied as the argument to this option and continues
103 running until the command exits. If the command terminates nor‐
104 mally, direvent exits with the code returned by it. If the com‐
105 mand terminates on SIGHUP, direvent exits with code 0. If it
106 terminates on another signal, direvent exits with code 2.
107 COMMAND can include any command line options or arguments, pro‐
109 vided that it is properly quoted. It is invoked as /bin/sh -c
110 COMMAND in the environment of the parent direvent process.
111 The macro variable $self_test_pid holds the PID of the COMMAND
113 (see section MACRO EXPANSION in direvent.conf(5)).
114 -t, --lint
116 Check configuration file for errors and exit.
117 -u, --user=USER
119 Run as this USER.
120 Informative options cause the program to display the requested piece of
122 information and exit:
123 -h, --help
125 Output a terse help summary and exit.
126 -H, --config-help
128 Describe configuration file syntax.
129 --usage
131 Show available command line options.
132 -V, --version
134 Print program version and copyright information.
135
137 The default configuration file is /etc/direvent.conf. If a file name
138 is supplied as an argument to the program, that file will be read in‐
139 stead.
140 The configuration file syntax is discussed in detail in di‐
142 revent.conf(5). This section provides only a short description of it.
143 Three types of comments are allowed: inline comments, that begin with a
145 # or // and extend to the end of line, and multi-line comments, which
146 comprise everything enclosed between /* and */. Comments and empty
147 lines are ignored. Whitespace characters are ignored as well, except
148 as they serve to separate tokens.
149 A token is a string of consecutive characters from the following
151 classes: alphanumeric characters, underscores, dots, asteriscs,
152 slashes, semicolons, commercial at's, and dashes.
153 Any other sequence of characters must be enclosed in double quotation
155 marks in order to represent a single token.
156 Adjacent quoted strings are concatenated.
158 Configuration statements consist of a keyword and value separated by
160 any amount of whitespace and is terminated with a semicolon. A block
161 statement is a collection of statements enclosed in curly braces.
162 The most important configuration statement is watcher. It is defined
164 as follows:
165 watcher {
167 path PATHNAME [recursive [LEVEL]];
168 event EVENT-LIST;
169 command COMMAND-LINE;
170 user NAME;
171 timeout NUMBER;
172 environ ENV-SPEC;
173 option STRING-LIST;
174 }
175 Each watcher statement instructs direvent to monitor the events listed
177 in EVENT-LIST occurring in the directories specified by PATHNAMEs in
178 path statements (any number of path statements can be given). When any
179 such event is detected, the COMMAND-LINE will be executed.
180 Each directory defined with the recursive keyword will be watched re‐
182 cursively. This means that for each subdirectory created in it, di‐
183 revent will install a watcher similar to that of its parent directory.
184 The optional LEVEL can be used to set up a cut-off nesting level, be‐
185 yond which the recursive operation is disabled.
186 The PATHNAME is not required to be a directory, it can as well be a
188 file of any type. This file is not required to exist, either. If it
189 does not, direvent will defer configuring the watcher until the file is
190 eventually created.
191 The rest of statements are optional. The user statement can be used to
193 execute the COMMAND-LINE as the user NAME (provided, of course, that
194 direvent is started with root privileges). The timeout specifies the
195 maximum amount of time (in seconds) the command is allowed to run. It
196 defaults to 5. The environ statement modifies the command environment
197 (see the following section). Finally, the option statement supplies
198 additional options. It can be used, for example, to divert the com‐
199 mand's output to syslog.
200 The program's logging is controlled by the debug and syslog statements.
202 debug NUMBER;
204 Sets the debugging level to NUMBER -- an integer value between 0
205 and 3. Zero is the default and means the debugging is disabled.
206 The bigger the NUMBER the more detailed debugging information
207 will be output.
208 The syslog statement controls the syslog logging:
210 syslog {
212 facility STRING;
213 tag STRING;
214 print-priority BOOL;
215 }
216 The pidfile statement instructs the program to write its PID to
218 the named file after disconnecting from the controlling terminal.
219
221 The handler to be executed on an event is defined by the command state‐
222 ment in the watcher configuration block (see direvent.conf(5)). Before
223 executing, the following operations are performed:
224 1. The current working directory is set to the directory where the
226 event occurred.
227 2. If the environ statement is present in the watcher, the environ‐
229 ment is modified according to its rules. See the description of
230 the environ statement in direvent.conf(5).
231 3. The standard input is closed.
233 If the stdout option is supplied, the standard output is cap‐
235 tured and redirected to the syslog. Otherwise it is closed.
236 If the stderr option is supplied, the standard error is captured
238 and redirected to the syslog. Otherwise it is closed.
239 All file descriptors above 2 are closed.
241 4. Macro variables are expanded. See the section MACRO EXPANSION
243 in direvent.conf(5). For example, if the handler is about to be
244 executed for the write event on the file somefile, and the com‐
245 mand definition was:
246 command "/libexec/handler -e '$genev_name' -f '$file'";
248 then the resulting command line will be:
250 /libexec/handler -e 'open' -f 'somefile'
252 5. Word splitting is performed on the resulting command line. The
254 first word is treated as the pathname of the program to be exe‐
255 cuted.
256 6. The program is invoked.
258
260 Direvent relies on the event monitoring API provided by the kernel.
261
263 On Linux the program uses inotify(7).
264 The maximum number of watches a user process can have is controlled by
266 the fs.inotify.max_user_watches system variable. Normally it is set to
267 8192, which is quite enough for most purposes. However, if you monitor
268 a big number or directories and/or are using recursive watchers, you
269 may need more watches. In that case, use sysctl(8) to raise the limit,
270 e.g.:
271 sysctl -w fs.inotify.max_user_watches=16384
273 Most GNU/Linux distributions provide the file /etc/sysctl.conf which
275 can be used to set this variable on startup.
276 The following system-dependent events are defined on systems that use
278 inotify(7):
279 ACCESS A file was accessed.
281 ATTRIB A file's metadata changed.
283 CLOSE_WRITE
285 A writable file was closed.
286 CLOSE_NOWRITE
288 An unwritable file closed.
289 CREATE A file was created.
291 DELETE A file was deleted.
293 MODIFY A file was modified.
295 MOVED_FROM
297 A file was moved into a monitored directory.
298 MOVED_TO
300 A file was moved out from a monitored directory.
301 OPEN A file was opened.
303
305 When compiled on BSD systems (including Darwin), direvent uses
306 kqueue(2). This interface needs an open file handle for each file in a
307 monitored directory, which means that the number of watchers is limited
308 by the maximum number of open files. Use ulimit -n NUM to raise it to
309 a higher number.
310 Since it operates on files, kqueue does not provide direct support for
312 the create generic event. Direvent works over this disadvantage by
313 keeping track of the contents of each monitored directory and rescan‐
314 ning it each time a WRITE system event is reported for it. It then
315 generates the open event for each file that appeared after the last
316 scan. Such a rescan can consume considerable time if a directory has a
317 very large number of files in it.
318 The following system-dependent events are available:
320 DELETE The unlink() system call was called on the monitored file.
322 WRITE A write occurred on the file.
324 EXTEND The file was extended.
326 ATTRIB The file attributes have changed.
328 LINK The link count on the file changed.
330 RENAME The file was renamed.
332 REVOKE Access to the file was revoked via revoke(2) or the underlying
334 file system was unmounted.
335
337 Essentially the same as BSD. The main difference compared to Linux and
338 BSD is that on Darwin the watchers are set after disconnecting from the
339 controlling terminal, because Darwin lacks the rfork(2) call and the
340 event queue cannot be inherited by the child process.
341
343 0 Successful termination.
344 1 Command line usage error.
346 2 Another error occurred.
348
350 direvent.conf(5), inotify(7), kqueue(2).
351
353 Sergey Poznyakoff
354
356 Report bugs to <bug-direvent@gnu.org.ua>.
357
359 Copyright © 2012, 2013 Sergey Poznyakoff
360 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li‐
361 censes/gpl.html>
362 This is free software: you are free to change and redistribute it.
363 There is NO WARRANTY, to the extent permitted by law.
364DIREVENT August 25, 2016 DIREVENT(8)