1fswatch(7) BSD Miscellaneous Information Manual fswatch(7)
3
5 fswatch — Ask for notification when the contents of the specified files
6 or directory hierarchies are modified.
7 This man page is kept for reference but it is not to be considered an au‐
9 thoritative or complete source of information. Please, consult the offi‐
10 cial Info documentation shipped with fswatch.
11
13 fswatch (option)* path+
14
16 The fswatch command receives notifications when the contents of the spec‐
17 ified files or directories are modified. fswatch implements six kind of
18 monitors:
19 - A monitor based on the File System Events API of Apple OS X.
21 - A monitor based on kqueue, an event notification interface intro‐
23 duces in FreeBSD 4.1 and supported on most *BSD systems (includ‐
24 ing OS X).
25 - A monitor based on the File Events Notification API of the So‐
27 laris kernel and its derivatives.
28 - A monitor based on inotify, a Linux kernel subsystem that reports
30 file system changes to applications.
31 - A monitor based on the ReadDirectoryChangesW Microsoft Windows
33 API.
34 - A monitor which periodically stats the file system, saves file
36 modification times in memory and manually calculates changes.
37 fswatch writes a record for each event it receives containing:
39 - The timestamp when the event was received (optionally).
41 - The path affected by the current event.
43 - A space-separated list of event types (see EVENT TYPES ).
45 fswatch enters an infinite loop and never returns. When it receives a
47 SIGABRT, SIGINT or SIGTERM signal, fswatch closes the notification
48 streams and exits gracefully returning 0 to the calling process.
49 The following options are available:
51 -0, --print0
53 Use the ASCII NUL character (\0) as line separator. Since file
54 names can potentially contain any character but NUL, this option
55 assures that the output of fswatch can be safely parsed using NUL
56 as delimiter, such as using xargs -0 and the shell builtin read
57 -d ''.
58 -1, --one-event
60 Exit fswatch after the first set of events is received.
61 --batch-marker marker
63 Print a marker at the end of every batch. An optional marker
64 marker can be specified to override its default value `NoOp'.
65 --event name
67 Filter event with the specified name. This option can be used
68 multiple times, one for each event name that must be included in
69 the output.
70 -e, --exclude regexp
72 Exclude paths matching regexp. Multiple exclude filters can be
73 specified using this option multiple times. See FILTERING PATHS
74 for further information.
75 -E, --extended
77 Use extended regular expressions.
78 -f, --format-time format
80 Print the event time using the specified format. Supported for‐
81 mats are specified by strftime(3).
82 -h, --help
84 Show the help message.
85 -i, --include regexp
87 Include paths matching regexp. Multiple include filters can be
88 specified using this option multiple times. See FILTERING PATHS
89 for further information.
90 -I, --insensitive
92 Use case insensitive regular expressions.
93 -l, --latency latency
95 Set the latency in seconds. The latency is a double value
96 greater than 0.1. Smaller values are currently not allowed in
97 order not to compromise the performance of the system. The de‐
98 fault latency is 1 second.
99 -L, --follow-links
101 Follow symbolic links.
102 -M, --list-monitors
104 List the available monitors.
105 -m, --monitor name
107 Uses the monitor specified by name. The list of currently avail‐
108 able monitors can be obtained using the -h option.
109 -n, --numeric
111 Print the numeric value of the event flag, instead of the array
112 of symbolic names. The numeric value of the event flags are sys‐
113 tem-specific and may vary across different versions of OS X. As
114 a consequence, the use of numeric values is discouraged.
115 -o, --one-per-batch
117 Print a single message with the number of change events.
118 -r, --recursive
120 Watch subdirectories recursively. This option may not be sup‐
121 ported on all systems.
122 -t, --timestamp
124 Print the event timestamp.
125 -u, --utf-time
127 Print the event time in UTC format. When this option is not
128 specified, the time is printed using the system local time, as
129 defined by localtime (3).
130 -v, --verbose
132 Print verbose output.
133 --version
135 Print the version of fswatch and exits.
136 -x, --event-flags
138 Prints the event flags.
139 --event-flag-separator separator
141 Print event flags using the specified separator.
142
144 fswatch acts as a front-end to system-specific monitors. Currently, the
145 available monitors are:
146 - The FSEvents monitor, a monitor based on the File System Events
148 API of Apple OS X.
149 - The kqueue monitor, a monitor based on kqueue, an event notifica‐
151 tion interface introduced in FreeBSD 4.1 and supported on most
152 *BSD systems (including OS X).
153 - The inotify monitor, a Linux kernel subsystem that reports file
155 system changes to applications.
156 - The poll monitor, a monitor which periodically stats the file
158 system, saves file modification times in memory and manually cal‐
159 culates file system changes, which can work on any operating sys‐
160 tem where stat(2) can be used.
161 Each monitor has its own strengths, weakness and peculiarities. Although
163 fswatch strives to provide a uniform experience no matter which monitor
164 is used, it is still important for users to know which monitor they are
165 using and to be aware of existing bugs, limitations, corner cases or
166 pathological behaviour.
167 The FSEvents Monitor
169 The FSEvents monitor, available only on Apple OS X, has no known limita‐
170 tions and scales very well with the number of files being observed. In
171 fact, I observed no performance degradation when testing fswatch observ‐
172 ing changes on a filesystem of 500 GB over long periods of time. On OS
173 X, this is the default monitor.
174 The kqueue Monitor
176 The kqueue monitor, available on any *BSD system featuring kqueue, re‐
177 quires a file descriptor to be opened for every file being watched. As a
178 result, this monitor scales badly with the number of files being observed
179 and may begin to misbehave as soon as the fswatch process runs out of
180 file descriptors. In this case, fswatch dumps one error on standard er‐
181 ror for every file that cannot be opened. Beware that on some systems
182 the maximum number of file descriptors that can be opened by a process is
183 set to a very low value (values as low as 256 are not uncommon), even if
184 the operating system may allow a much larger value.
185 If you are running out of file descriptors when using this monitor and
187 you cannot reduce the number of observed items, either:
188 - Consider raising the number of maximum open file descriptors
190 (check your OS documentation).
191 - Consider using another monitor.
193 The inotify Monitor
195 The inotify monitor, available on Linux since kernel 2.6.13, may suffer a
196 queue overflow if events are generated faster than they are read from the
197 queue. In any case, the application is guaranteed to receive an overflow
198 notification which can be handled to gracefully recover. fswatch cur‐
199 rently throws an exception if a queue overflow occurs. Future versions
200 will handle the overflow by emitting proper notifications. However, the
201 odds of observing a queue overflow on a default configured mainstream
202 GNU/Linux distribution is very low.
203 The inotify API sends events for the direct child elements of a watched
205 directory and it scales pretty well with the number of watched items.
206 For this reason, depending on the number of files to watch, it may some‐
207 times be preferable to watch a common parent directory and filter re‐
208 ceived events rather than adding a huge number of file watches.
209 The Poll Monitor
211 The poll monitor was added as a fallback mechanisms in the cases where no
212 other monitor could be used, including:
213 - Operating system without any sort of file events API.
215 - Situations where the limitations of the available monitors cannot
217 be overcome (i.e.: observing a number of files greater than the
218 available file descriptors on a system using the kqueue monitor).
219 The poll monitor, available on any platform, only relies on available CPU
221 and memory to perform its task (besides the stat(2) function). The per‐
222 formance of this monitor degrades linearly with the number of files being
223 watched. The authors' experience indicates that fswatch requires approx‐
224 imately 150 MB or RAM memory to observe a hierarchy of 500.000 files with
225 a minimum path length of 32 characters. A common bottleneck of the poll
226 monitor is disk access, since stat()-ing a great number of files may take
227 a huge amount of time. In this case, the latency should be set to a suf‐
228 ficiently large value in order to reduce the performance degradation that
229 may result from frequent disk access.
230 How to Choose a Monitor
232 fswatch already chooses the "best" monitor for your platform if you do
233 not specify any. However, a specific monitor may be better suited to
234 specific use cases. Please, read the MONITORS section to get a descrip‐
235 tion of all the available monitors and their limitations.
236 Usage recommendations are as follows:
238 - On OS X, use only the FSEvents monitor (which is the default be‐
240 haviour).
241 - On Linux, use the inotify monitor (which is the default behav‐
243 iour).
244 - If the number of files to observe is sufficiently small, use the
246 kqueue monitor. Beware that on some systems the maximum number
247 of file descriptors that can be opened by a process is set to a
248 very low value (values as low as 256 are not uncommon), even if
249 the operating system may allow a much larger value. In this
250 case, check your OS documentation to raise this limit on either a
251 per process or a system-wide basis.
252 - If feasible, watch directories instead of watching files. Prop‐
254 erly crafting the receiving side of the events to deal with di‐
255 rectories may sensibly reduce the monitor resource consumption.
256 - If none of the above applies, use the poll monitor. The authors'
258 experience indicates that fswatch requires approximately 150 MB
259 or RAM memory to observe a hierarchy of 500.000 files with a min‐
260 imum path length of 32 characters. A common bottleneck of the
261 poll monitor is disk access, since stat()-ing a great number of
262 files may take a huge amount of time. In this case, the latency
263 should be set to a sufficiently large value in order to reduce
264 the performance degradation that may result from frequent disk
265 access.
266
268 Received events can be filtered by path using regular expressions. Regu‐
269 lar expressions can be used to include or exclude matching paths. The
270 user can specify multiple filter expression in any order and the first
271 matching expression wins.
272 Other options govern how regular expressions are interpreted:
274 - Regular expressions can be extended if option -E is specified.
276 - Regular expressions can be case insensitive if option -I is spec‐
278 ified.
279
281 Basic Usage
282 fswatch syntax is the following:
283 $ fswatch [options] [paths] ...
285 fswatch will then output change events to standard output. By default,
287 only the affected file name is printed. However, many options are avail‐
288 able to format the event record, including:
289 - The possibility of adding the event timestamp.
291 - The possibility of adding the event mask in both textual and nu‐
293 merical form.
294 The following command listens for changes in the current directory and
296 events are delivered every 5 seconds:
297 $ fswatch -l 5 .
299 The following command listens for changes in the current user home direc‐
301 tory and /var/log:
302 $ fswatch ~ /var/log
304 Piping fswatch Output to Another Process
306 Very often you wish to not only receive an event, but react to it. The
307 simplest way to do it is piping fswatch output to another process. Since
308 in Unix and Unix-like file system file names may potentially contain any
309 character but NUL (\0) and the path separator (/), fswatch has a specific
310 mode of operation when its output must be piped to another process. When
311 the [-0] option is used, fswatch will use the NUL character as record
312 separator, thus allowing any other character to appear in a path. This
313 is important because many commands and shell builtins (such as read)
314 split words and lines by default using the characters in $IFS, which by
315 default contains characters which may be present (although rarely) in a
316 file name, resulting in a wrong event path being received and processed.
317 Probably the simplest way to pipe fswatch to another program in order to
319 respond to an event is using xargs:
320 $ fswatch -0 [opts] [paths] | xargs -0 -n 1 -I {} [command]
322 - fswatch -0 will split records using the NUL character.
324 - xargs -0 will split records using the NUL character. This is re‐
326 quired to correctly match impedance with fswatch.
327 - xargs -n 1 will invoke command every record. If you want to do
329 it every x records, then use xargs -n x.
330 - xargs -I {} will substitute occurrences of {} in command with the
332 parsed argument. If the command you are running does not need
333 the event path name, just delete this option. If you prefer us‐
334 ing another replacement string, substitute {} with yours.
335 Bubbling Events
337 An often requested feature is being able to receive a single event "per
338 batch", instead of receiving multiple events. This use case is imple‐
339 mented by the [-o, --one-per-batch] option which tells fswatch to dump a
340 record containing the number of received events, without any other de‐
341 tail:
342 $ fswatch -or /path/to/watch
344 1
345 10
346 [...]
347 This is useful if, for example, you want to respond to change events in a
349 way which is (or can easily be) path-independent (because you are not re‐
350 ceiving any event detail) and you prefer to "bubble" events together to
351 reduce the overhead of the command being executed. A typical case is a
352 directory synchronisation job whenever some files change.
353 Receiving a Single Event
355 Another requested feature is the possibility of receiving a single event
356 and exit. This is most useful when existing scripts processing events
357 include the restart logic of fswatch This use case is implemented by the
358 [-1, --one-event] option:
359 $ fswatch -1 /path/to/watch
361 /path/to/watch
362
364 The previous major version of fswatch (v. 0.x) allowed users to run a
365 command whenever a set of changes was detected with the following syntax:
366 $ fswatch path program
368 Starting with fswatch v. 1.x this behaviour is no longer supported. The
370 rationale behind this decision includes:
371 - The old version only allows watching one path.
373 - The command to execute was passed as last argument, alongside the
375 path to watch, making it difficult to extend the program func‐
376 tionality to add multiple path support
377 - The old version forks and executes /bin/bash, which is neither
379 portable, nor guaranteed to succeed, nor desirable by users of
380 other shells.
381 - No information about the change events is passed to the forked
383 process.
384 To solve the aforementioned issues and keep fswatch consistent with com‐
386 mon UNIX practices, the behaviour has changed and fswatch now prints
387 event records to the standard output that users can process further by
388 piping the output of fswatch to other programs.
389 To fully support the old use, the [-o, --one-per-batch] option was added
391 in v. 1.3.3. When specified, fswatch will only dump 1 event to standard
392 output which can be used to trigger another program:
393 $ fswatch -o path | xargs -n1 program
395 In this case, program will receive the number of change events as first
397 argument. If no argument should be passed to program, then the following
398 command could be used:
399 $ fswatch -o path | xargs -n1 -I{} program
401 Although we encourage you to embrace the new fswatch behaviour and update
403 your scripts, we provide a little wrapper called fswatch-run which is in‐
404 stalled alongside fswatch which lets you use the legacy syntax:
405 $ fswatch-run path [paths] program
407 Under the hood, fswatch-run simply calls fswatch -o piping its output to
409 xargs.
410 fswatch-run is a symbolic link to a shell-specific wrapper. Currently,
412 ZSH and Bash scripts are provided. If no suitable shells are found in
413 the target system, the fswatch-run symbolic link is not created.
414
416 fswatch may exit with one of the following exit statuses:
417 FSW_OK 0
419 FSW_ERR_UNKNOWN_ERROR (1 << 0)
420 FSW_ERR_SESSION_UNKNOWN (1 << 1)
421 FSW_ERR_MONITOR_ALREADY_EXISTS (1 << 2)
422 FSW_ERR_MEMORY (1 << 3)
423 FSW_ERR_UNKNOWN_MONITOR_TYPE (1 << 4)
424 FSW_ERR_CALLBACK_NOT_SET (1 << 5)
425 FSW_ERR_PATHS_NOT_SET (1 << 6)
426 FSW_ERR_UNKNOWN_MONITOR (1 << 7)
427 FSW_ERR_MISSING_CONTEXT (1 << 8)
428 FSW_ERR_INVALID_PATH (1 << 9)
429 FSW_ERR_INVALID_CALLBACK (1 << 10)
430 FSW_ERR_INVALID_LATENCY (1 << 11)
431 FSW_ERR_INVALID_REGEX (1 << 12)
432 FSW_ERR_MONITOR_ALREADY_RUNNING (1 << 13)
433 FSW_ERR_STALE_MONITOR_THREAD (1 << 14)
434 FSW_ERR_THREAD_FAULT (1 << 15)
435 FSW_ERR_UNSUPPORTED_OPERATION (1 << 16)
436 FSW_ERR_UNKNOWN_VALUE (1 << 17)
437
439 fswatch exits 0 on success, and >0 if an error occurs.
440
442 fswatch can be built on any system supporting at least one of the avail‐
443 able monitors.
444
446 See https://github.com/emcrisostomo/fswatch/issues for open issues or to
447 create a new one.
448 Bugs can also be submitted to enrico.m.crisostomo@gmail.com.
450redhat linux-gnu July 19, 2023 redhat linux-gnu