1
2fswatch(7)           BSD Miscellaneous Information Manual           fswatch(7)
3

NAME

5     fswatch — Ask for notification when the contents of the specified files
6     or directory hierarchies are modified.
7
8     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

SYNOPSIS

13     fswatch (option)* path+
14

DESCRIPTION

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
20     -       A monitor based on the File System Events API of Apple OS X.
21
22     -       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
26     -       A monitor based on the File Events Notification API of the So‐
27             laris kernel and its derivatives.
28
29     -       A monitor based on inotify, a Linux kernel subsystem that reports
30             file system changes to applications.
31
32     -       A monitor based on the ReadDirectoryChangesW Microsoft Windows
33             API.
34
35     -       A monitor which periodically stats the file system, saves file
36             modification times in memory and manually calculates changes.
37
38     fswatch writes a record for each event it receives containing:
39
40     -       The timestamp when the event was received (optionally).
41
42     -       The path affected by the current event.
43
44     -       A space-separated list of event types (see EVENT TYPES ).
45
46     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
50     The following options are available:
51
52     -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
59     -1, --one-event
60             Exit fswatch after the first set of events is received.
61
62     --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
66     --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
71     -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
76     -E, --extended
77             Use extended regular expressions.
78
79     -f, --format-time format
80             Print the event time using the specified format.  Supported for‐
81             mats are specified by strftime(3).
82
83     -h, --help
84             Show the help message.
85
86     -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
91     -I, --insensitive
92             Use case insensitive regular expressions.
93
94     -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
100     -L, --follow-links
101             Follow symbolic links.
102
103     -M, --list-monitors
104             List the available monitors.
105
106     -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
110     -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
116     -o, --one-per-batch
117             Print a single message with the number of change events.
118
119     -r, --recursive
120             Watch subdirectories recursively.  This option may not be sup‐
121             ported on all systems.
122
123     -t, --timestamp
124             Print the event timestamp.
125
126     -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
131     -v, --verbose
132             Print verbose output.
133
134     --version
135             Print the version of fswatch and exits.
136
137     -x, --event-flags
138             Prints the event flags.
139
140     --event-flag-separator separator
141             Print event flags using the specified separator.
142

MONITORS

144     fswatch acts as a front-end to system-specific monitors.  Currently, the
145     available monitors are:
146
147     -       The FSEvents monitor, a monitor based on the File System Events
148             API of Apple OS X.
149
150     -       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
154     -       The inotify monitor, a Linux kernel subsystem that reports file
155             system changes to applications.
156
157     -       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
162     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
168   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
175   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
186     If you are running out of file descriptors when using this monitor and
187     you cannot reduce the number of observed items, either:
188
189     -       Consider raising the number of maximum open file descriptors
190             (check your OS documentation).
191
192     -       Consider using another monitor.
193
194   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
204     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
210   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
214     -       Operating system without any sort of file events API.
215
216     -       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
220     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
231   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
237     Usage recommendations are as follows:
238
239     -       On OS X, use only the FSEvents monitor (which is the default be‐
240             haviour).
241
242     -       On Linux, use the inotify monitor (which is the default behav‐
243             iour).
244
245     -       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
253     -       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
257     -       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

FILTERING PATHS

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
273     Other options govern how regular expressions are interpreted:
274
275     -       Regular expressions can be extended if option -E is specified.
276
277     -       Regular expressions can be case insensitive if option -I is spec‐
278             ified.
279

EXAMPLES

281   Basic Usage
282     fswatch syntax is the following:
283
284           $ fswatch [options] [paths] ...
285
286     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
290     -       The possibility of adding the event timestamp.
291
292     -       The possibility of adding the event mask in both textual and nu‐
293             merical form.
294
295     The following command listens for changes in the current directory and
296     events are delivered every 5 seconds:
297
298           $ fswatch -l 5 .
299
300     The following command listens for changes in the current user home direc‐
301     tory and /var/log:
302
303           $ fswatch ~ /var/log
304
305   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
318     Probably the simplest way to pipe fswatch to another program in order to
319     respond to an event is using xargs:
320
321           $ fswatch -0 [opts] [paths] | xargs -0 -n 1 -I {} [command]
322
323     -       fswatch -0 will split records using the NUL character.
324
325     -       xargs -0 will split records using the NUL character. This is re‐
326             quired to correctly match impedance with fswatch.
327
328     -       xargs -n 1 will invoke command every record.  If you want to do
329             it every x records, then use xargs -n x.
330
331     -       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
336   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
343           $ fswatch -or /path/to/watch
344           1
345           10
346           [...]
347
348     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
354   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
360           $ fswatch -1 /path/to/watch
361           /path/to/watch
362

Compatibility With fswatch 0.x

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
367           $ fswatch path program
368
369     Starting with fswatch v. 1.x this behaviour is no longer supported.  The
370     rationale behind this decision includes:
371
372     -       The old version only allows watching one path.
373
374     -       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
378     -       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
382     -       No information about the change events is passed to the forked
383             process.
384
385     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
390     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
394           $ fswatch -o path | xargs -n1 program
395
396     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
400           $ fswatch -o path | xargs -n1 -I{} program
401
402     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
406           $ fswatch-run path [paths] program
407
408     Under the hood, fswatch-run simply calls fswatch -o piping its output to
409     xargs.
410
411     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

EXIT STATUS

416     fswatch may exit with one of the following exit statuses:
417
418           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

DIAGNOSTICS

439     fswatch exits 0 on success, and >0 if an error occurs.
440

COMPATIBILITY

442     fswatch can be built on any system supporting at least one of the avail‐
443     able monitors.
444

BUGS

446     See https://github.com/emcrisostomo/fswatch/issues for open issues or to
447     create a new one.
448
449     Bugs can also be submitted to enrico.m.crisostomo@gmail.com.
450
451redhat linux-gnu                 July 19, 2023                redhat linux-gnu
Impressum