Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
fswatch(7)	   FreeBSD Miscellaneous Information Manual	    fswatch(7)

NAME
     fswatch --	Ask for	notification when the contents of the specified	files
     or	directory hierarchies are modified.

     This man page is kept for reference but it	is not to be considered	an au-
     thoritative or complete source of information.  Please, consult the offi-
     cial Info documentation shipped with fswatch.

SYNOPSIS
     fswatch (option)* path+

DESCRIPTION
     The fswatch command receives notifications	when the contents of the spec-
     ified files or directories	are modified.  fswatch implements six kind of
     monitors:

     -	     A monitor based on	the File System	Events API of Apple OS X.

     -	     A monitor based on	kqueue,	an event notification interface	intro-
	     duces in FreeBSD 4.1 and supported	on most	*BSD systems (includ-
	     ing OS X).

     -	     A monitor based on	the File Events	Notification API of the	So-
	     laris kernel and its derivatives.

     -	     A monitor based on	inotify, a Linux kernel	subsystem that reports
	     file system changes to applications.

     -	     A monitor based on	the ReadDirectoryChangesW Microsoft Windows
	     API.

     -	     A monitor which periodically stats	the file system, saves file
	     modification times	in memory and manually calculates changes.

     fswatch writes a record for each event it receives	containing:

     -	     The timestamp when	the event was received (optionally).

     -	     The path affected by the current event.

     -	     A space-separated list of event types (see	EVENT TYPES ).

     fswatch enters an infinite	loop and never returns.	 When it receives a
     SIGABRT, SIGINT or	SIGTERM	signal,	fswatch	closes the notification
     streams and exits gracefully returning 0 to the calling process.

     The following options are available:

     -0, --print0
	     Use the ASCII NUL character (\0) as line separator.  Since	file
	     names can potentially contain any character but NUL, this option
	     assures that the output of	fswatch	can be safely parsed using NUL
	     as	delimiter, such	as using xargs -0 and the shell	builtin	read
	     -d	''.

     -1, --one-event
	     Exit fswatch after	the first set of events	is received.

     --batch-marker marker
	     Print a marker at the end of every	batch.	An optional marker
	     marker can	be specified to	override its default value `NoOp'.

     --event name
	     Filter event with the specified name.  This option	can be used
	     multiple times, one for each event	name that must be included in
	     the output.

     -e, --exclude regexp
	     Exclude paths matching regexp.  Multiple exclude filters can be
	     specified using this option multiple times.  See FILTERING	PATHS
	     for further information.

     -E, --extended
	     Use extended regular expressions.

     -f, --format-time format
	     Print the event time using	the specified format.  Supported for-
	     mats are specified	by strftime(3).

     -h, --help
	     Show the help message.

     -i, --include regexp
	     Include paths matching regexp.  Multiple include filters can be
	     specified using this option multiple times.  See FILTERING	PATHS
	     for further information.

     -I, --insensitive
	     Use case insensitive regular expressions.

     -l, --latency latency
	     Set the latency in	seconds.  The latency is a double value
	     greater than 0.1.	Smaller	values are currently not allowed in
	     order not to compromise the performance of	the system.  The de-
	     fault latency is 1	second.

     -L, --follow-links
	     Follow symbolic links.

     -M, --list-monitors
	     List the available	monitors.

     -m, --monitor name
	     Uses the monitor specified	by name.  The list of currently	avail-
	     able monitors can be obtained using the -h	option.

     -n, --numeric
	     Print the numeric value of	the event flag,	instead	of the array
	     of	symbolic names.	 The numeric value of the event	flags are sys-
	     tem-specific and may vary across different	versions of OS X.  As
	     a consequence, the	use of numeric values is discouraged.

     -o, --one-per-batch
	     Print a single message with the number of change events.

     -r, --recursive
	     Watch subdirectories recursively.	This option may	not be sup-
	     ported on all systems.

     -t, --timestamp
	     Print the event timestamp.

     -u, --utf-time
	     Print the event time in UTC format.  When this option is not
	     specified,	the time is printed using the system local time, as
	     defined by	localtime (3).

     -v, --verbose
	     Print verbose output.

     --version
	     Print the version of fswatch and exits.

     -x, --event-flags
	     Prints the	event flags.

     --event-flag-separator separator
	     Print event flags using the specified separator.

MONITORS
     fswatch acts as a front-end to system-specific monitors.  Currently, the
     available monitors	are:

     -	     The FSEvents monitor, a monitor based on the File System Events
	     API of Apple OS X.

     -	     The kqueue	monitor, a monitor based on kqueue, an event notifica-
	     tion interface introduced in FreeBSD 4.1 and supported on most
	     *BSD systems (including OS	X).

     -	     The inotify monitor, a Linux kernel subsystem that	reports	file
	     system changes to applications.

     -	     The poll monitor, a monitor which periodically stats the file
	     system, saves file	modification times in memory and manually cal-
	     culates file system changes, which	can work on any	operating sys-
	     tem where stat(2) can be used.

     Each monitor has its own strengths, weakness and peculiarities.  Although
     fswatch strives to	provide	a uniform experience no	matter which monitor
     is	used, it is still important for	users to know which monitor they are
     using and to be aware of existing bugs, limitations, corner cases or
     pathological behaviour.

   The FSEvents	Monitor
     The FSEvents monitor, available only on Apple OS X, has no	known limita-
     tions and scales very well	with the number	of files being observed.  In
     fact, I observed no performance degradation when testing fswatch observ-
     ing changes on a filesystem of 500	GB over	long periods of	time.  On OS
     X,	this is	the default monitor.

   The kqueue Monitor
     The kqueue	monitor, available on any *BSD system featuring	kqueue,	re-
     quires a file descriptor to be opened for every file being	watched.  As a
     result, this monitor scales badly with the	number of files	being observed
     and may begin to misbehave	as soon	as the fswatch process runs out	of
     file descriptors.	In this	case, fswatch dumps one	error on standard er-
     ror for every file	that cannot be opened.	Beware that on some systems
     the maximum number	of file	descriptors that can be	opened by a process is
     set to a very low value (values as	low as 256 are not uncommon), even if
     the operating system may allow a much larger value.

     If	you are	running	out of file descriptors	when using this	monitor	and
     you cannot	reduce the number of observed items, either:

     -	     Consider raising the number of maximum open file descriptors
	     (check your OS documentation).

     -	     Consider using another monitor.

   The inotify Monitor
     The inotify monitor, available on Linux since kernel 2.6.13, may suffer a
     queue overflow if events are generated faster than	they are read from the
     queue.  In	any case, the application is guaranteed	to receive an overflow
     notification which	can be handled to gracefully recover.  fswatch cur-
     rently throws an exception	if a queue overflow occurs.  Future versions
     will handle the overflow by emitting proper notifications.	 However, the
     odds of observing a queue overflow	on a default configured	mainstream
     GNU/Linux distribution is very low.

     The inotify API sends events for the direct child elements	of a watched
     directory and it scales pretty well with the number of watched items.
     For this reason, depending	on the number of files to watch, it may	some-
     times be preferable to watch a common parent directory and	filter re-
     ceived events rather than adding a	huge number of file watches.

   The Poll Monitor
     The poll monitor was added	as a fallback mechanisms in the	cases where no
     other monitor could be used, including:

     -	     Operating system without any sort of file events API.

     -	     Situations	where the limitations of the available monitors	cannot
	     be	overcome (i.e.:	observing a number of files greater than the
	     available file descriptors	on a system using the kqueue monitor).

     The poll monitor, available on any	platform, only relies on available CPU
     and memory	to perform its task (besides the stat(2) function).  The per-
     formance of this monitor degrades linearly	with the number	of files being
     watched.  The authors' experience indicates that fswatch requires approx-
     imately 150 MB or RAM memory to observe a hierarchy of 500.000 files with
     a minimum path length of 32 characters.  A	common bottleneck of the poll
     monitor is	disk access, since stat()-ing a	great number of	files may take
     a huge amount of time.  In	this case, the latency should be set to	a suf-
     ficiently large value in order to reduce the performance degradation that
     may result	from frequent disk access.

   How to Choose a Monitor
     fswatch already chooses the "best"	monitor	for your platform if you do
     not specify any.  However,	a specific monitor may be better suited	to
     specific use cases.  Please, read the MONITORS section to get a descrip-
     tion of all the available monitors	and their limitations.

     Usage recommendations are as follows:

     -	     On	OS X, use only the FSEvents monitor (which is the default be-
	     haviour).

     -	     On	Linux, use the inotify monitor (which is the default behav-
	     iour).

     -	     If	the number of files to observe is sufficiently small, use the
	     kqueue monitor.  Beware that on some systems the maximum number
	     of	file descriptors that can be opened by a process is set	to a
	     very low value (values as low as 256 are not uncommon), even if
	     the operating system may allow a much larger value.  In this
	     case, check your OS documentation to raise	this limit on either a
	     per process or a system-wide basis.

     -	     If	feasible, watch	directories instead of watching	files.	Prop-
	     erly crafting the receiving side of the events to deal with di-
	     rectories may sensibly reduce the monitor resource	consumption.

     -	     If	none of	the above applies, use the poll	monitor.  The authors'
	     experience	indicates that fswatch requires	approximately 150 MB
	     or	RAM memory to observe a	hierarchy of 500.000 files with	a min-
	     imum path length of 32 characters.	 A common bottleneck of	the
	     poll monitor is disk access, since	stat()-ing a great number of
	     files may take a huge amount of time.  In this case, the latency
	     should be set to a	sufficiently large value in order to reduce
	     the performance degradation that may result from frequent disk
	     access.

FILTERING PATHS
     Received events can be filtered by	path using regular expressions.	 Regu-
     lar expressions can be used to include or exclude matching	paths.	The
     user can specify multiple filter expression in any	order and the first
     matching expression wins.

     Other options govern how regular expressions are interpreted:

     -	     Regular expressions can be	extended if option -E is specified.

     -	     Regular expressions can be	case insensitive if option -I is spec-
	     ified.

EXAMPLES
   Basic Usage
     fswatch syntax is the following:

	   $ fswatch [options] [paths] ...

     fswatch will then output change events to standard	output.	By default,
     only the affected file name is printed.  However, many options are	avail-
     able to format the	event record, including:

     -	     The possibility of	adding the event timestamp.

     -	     The possibility of	adding the event mask in both textual and nu-
	     merical form.

     The following command listens for changes in the current directory	and
     events are	delivered every	5 seconds:

	   $ fswatch -l	5 .

     The following command listens for changes in the current user home	direc-
     tory and /var/log:

	   $ fswatch ~ /var/log

   Piping fswatch Output to Another Process
     Very often	you wish to not	only receive an	event, but react to it.	 The
     simplest way to do	it is piping fswatch output to another process.	 Since
     in	Unix and Unix-like file	system file names may potentially contain any
     character but NUL (\0) and	the path separator (/),	fswatch	has a specific
     mode of operation when its	output must be piped to	another	process.  When
     the [-0] option is	used, fswatch will use the NUL character as record
     separator,	thus allowing any other	character to appear in a path.	This
     is	important because many commands	and shell builtins (such as read)
     split words and lines by default using the	characters in $IFS, which by
     default contains characters which may be present (although	rarely)	in a
     file name,	resulting in a wrong event path	being received and processed.

     Probably the simplest way to pipe fswatch to another program in order to
     respond to	an event is using xargs:

	   $ fswatch -0	[opts] [paths] | xargs -0 -n 1 -I {} [command]

     -	     fswatch -0	will split records using the NUL character.

     -	     xargs -0 will split records using the NUL character. This is re-
	     quired to correctly match impedance with fswatch.

     -	     xargs -n 1	will invoke command every record.  If you want to do
	     it	every x	records, then use xargs	-n x.

     -	     xargs -I {} will substitute occurrences of	{} in command with the
	     parsed argument.  If the command you are running does not need
	     the event path name, just delete this option.  If you prefer us-
	     ing another replacement string, substitute	{} with	yours.

   Bubbling Events
     An	often requested	feature	is being able to receive a single event	"per
     batch", instead of	receiving multiple events.  This use case is imple-
     mented by the [-o,	--one-per-batch] option	which tells fswatch to dump a
     record containing the number of received events, without any other	de-
     tail:

	   $ fswatch -or /path/to/watch
	   1
	   10
	   [...]

     This is useful if,	for example, you want to respond to change events in a
     way which is (or can easily be) path-independent (because you are not re-
     ceiving any event detail) and you prefer to "bubble" events together to
     reduce the	overhead of the	command	being executed.	 A typical case	is a
     directory synchronisation job whenever some files change.

   Receiving a Single Event
     Another requested feature is the possibility of receiving a single	event
     and exit.	This is	most useful when existing scripts processing events
     include the restart logic of fswatch This use case	is implemented by the
     [-1, --one-event] option:

	   $ fswatch -1	/path/to/watch
	   /path/to/watch

Compatibility With fswatch 0.x
     The previous major	version	of fswatch (v. 0.x) allowed users to run a
     command whenever a	set of changes was detected with the following syntax:

	   $ fswatch path program

     Starting with fswatch v. 1.x this behaviour is no longer supported.  The
     rationale behind this decision includes:

     -	     The old version only allows watching one path.

     -	     The command to execute was	passed as last argument, alongside the
	     path to watch, making it difficult	to extend the program func-
	     tionality to add multiple path support

     -	     The old version forks and executes	/bin/bash, which is neither
	     portable, nor guaranteed to succeed, nor desirable	by users of
	     other shells.

     -	     No	information about the change events is passed to the forked
	     process.

     To	solve the aforementioned issues	and keep fswatch consistent with com-
     mon UNIX practices, the behaviour has changed and fswatch now prints
     event records to the standard output that users can process further by
     piping the	output of fswatch to other programs.

     To	fully support the old use, the [-o, --one-per-batch] option was	added
     in	v. 1.3.3.  When	specified, fswatch will	only dump 1 event to standard
     output which can be used to trigger another program:

	   $ fswatch -o	path | xargs -n1 program

     In	this case, program will	receive	the number of change events as first
     argument.	If no argument should be passed	to program, then the following
     command could be used:

	   $ fswatch -o	path | xargs -n1 -I{} program

     Although we encourage you to embrace the new fswatch behaviour and	update
     your scripts, we provide a	little wrapper called fswatch-run which	is in-
     stalled alongside fswatch which lets you use the legacy syntax:

	   $ fswatch-run path [paths] program

     Under the hood, fswatch-run simply	calls fswatch -o piping	its output to
     xargs.

     fswatch-run is a symbolic link to a shell-specific	wrapper.  Currently,
     ZSH and Bash scripts are provided.	 If no suitable	shells are found in
     the target	system,	the fswatch-run	symbolic link is not created.

EXIT STATUS
     fswatch may exit with one of the following	exit statuses:

	   FSW_OK 0
	   FSW_ERR_UNKNOWN_ERROR (1 << 0)
	   FSW_ERR_SESSION_UNKNOWN (1 << 1)
	   FSW_ERR_MONITOR_ALREADY_EXISTS (1 <<	2)
	   FSW_ERR_MEMORY (1 <<	3)
	   FSW_ERR_UNKNOWN_MONITOR_TYPE	(1 << 4)
	   FSW_ERR_CALLBACK_NOT_SET (1 << 5)
	   FSW_ERR_PATHS_NOT_SET (1 << 6)
	   FSW_ERR_UNKNOWN_MONITOR (1 << 7)
	   FSW_ERR_MISSING_CONTEXT (1 << 8)
	   FSW_ERR_INVALID_PATH	(1 << 9)
	   FSW_ERR_INVALID_CALLBACK (1 << 10)
	   FSW_ERR_INVALID_LATENCY (1 << 11)
	   FSW_ERR_INVALID_REGEX (1 << 12)
	   FSW_ERR_MONITOR_ALREADY_RUNNING (1 << 13)
	   FSW_ERR_STALE_MONITOR_THREAD	(1 << 14)
	   FSW_ERR_THREAD_FAULT	(1 << 15)
	   FSW_ERR_UNSUPPORTED_OPERATION (1 << 16)
	   FSW_ERR_UNKNOWN_VALUE (1 << 17)

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

COMPATIBILITY
     fswatch can be built on any system	supporting at least one	of the avail-
     able monitors.

BUGS
     See https://github.com/emcrisostomo/fswatch/issues	for open issues	or to
     create a new one.

     Bugs can also be submitted	to enrico.m.crisostomo@gmail.com.

portbld	freebsd12.1		August 10, 2020		   portbld freebsd12.1

NAME | SYNOPSIS | DESCRIPTION | MONITORS | FILTERING PATHS | EXAMPLES | Compatibility With fswatch 0.x | EXIT STATUS | DIAGNOSTICS | COMPATIBILITY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fswatch&sektion=7&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help