fsw.7

.\"   $Id$
.\"
.\"   Man page for the fsw command.
.\"
.\"   $Log$
.\"
.Dd February 24, 2014
.Dt FSW "" "fsw file system monitor"
.Os "Darwin 10.0"
.An Enrico Maria Crisostomo
.Ad enrico.m.crisostomo@gmail.com
.Pp
.Sh NAME
.Nm fsw
.Nd Ask for notification when the contents of the specified files or directory
hierarchies are modified.

.Sh SYNOPSIS
.Nm fsw
.Op Fl 0EhIkLnprtuvx
.Op Fl e Ar regexp
.Op Fl f Ar format-time
.Op Fl i Ar regexp
.Op Fl l Ar latency

.Sh DESCRIPTION
The 
.Nm
command receives notifications when the contents of the specified files or
directories are modified.
fsw implements three kind of monitors:
.Bl -tag -width indent

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

.It -
A monitor based on kqueue, an event notification interface introduces in
FreeBSD 4.1 and supported on most *BSD systems (including OS X).

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

.El

.Nm
writes a record for each event it receives containing:
.Bl -tag -width indent
.It -
The timestamp when the event was
.Em received
(optionally).

.It -
The path affected by the current event.
.It -
A space-separated list of
.Em event types
(see 
.Sx EVENT TYPES
).
.El

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

.Pp
The following options are available:
.Bl -tag -width indent

.It Fl 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 fsw can be safely parsed using NUL as delimiter,
such as using xargs -0 and the shell builtin read -d ''. 

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

.It Fl E, -extended
Use extended regular expressions.

.It Fl f, -format-time Ar format
Print the event time using the specified
.Ar format .
Supported formats are specified by
.Sy strftime (3) .

.It Fl h, -help
Show the help message.

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

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

.It Fl k, -kqueue
Use the kqueue monitor.
This option is only available when more than one monitor is available, and one
of them is the kqueue monitor.

.It Fl l, -latency Ar latency
Set the
.Ar 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 default latency is 1 second.

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

.It Fl 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 system-specific and may vary across
different versions of OS X.
As a consequence, the use of numeric values is discouraged. 

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

.It Fl p, -poll
Use the poll-based monitor.
This monitor periodically stats the file system to detect changes on the
observed paths.
The time required by this monitor linearly increases with the number of files to
watch.
This monitor should be considered a last resource in case other monitors cannot
be used.  
 
.It Fl r, -recursive
Watch subdirectories recursively.  This option may not be supported on all
systems.

.It Fl t, -timestamp
Print the event timestamp.

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

.It Fl v, -verbose
Print verbose output.

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

.El

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

Other options govern how regular expressions are interpreted:
.Bl -tag -width indent
.It -
Regular expressions can be
.Em extended
if option
.Fl E
is specified.

.It -
Regular expressions can be
.Em case insensitive
if option
.Fl I
is specified.

.El

.Sh EVENT TYPES
The event types currently supported and the corresponding record symbols are:
.Bl -tag -width indent
.It -
kFSEventStreamEventFlagItemCreated, "created".

.It -
kFSEventStreamEventFlagItemRemoved, "removed".

.It -
kFSEventStreamEventFlagItemInodeMetaMod, "inodeMetaMod".

.It -
kFSEventStreamEventFlagItemRenamed, "renamed".

.It -
kFSEventStreamEventFlagItemModified, "modified".

.It -
kFSEventStreamEventFlagItemFinderInfoMod, "finderInfoMod".

.It -
kFSEventStreamEventFlagItemChangeOwner, "changeOwner".

.It -
kFSEventStreamEventFlagItemXattrMod, "xattrMod".

.It -
kFSEventStreamEventFlagItemIsFile, "isFile".

.It -
kFSEventStreamEventFlagItemIsDir, "isDir".

.It -
kFSEventStreamEventFlagItemIsSymlink, "isSymLink".

.El 

.Sh EXAMPLES
The following command listens for changes in the current directory and events
are delivered every 5 seconds:
.Pp
.Dl "$ fsw -l 5 ."
.Pp 
The following command listens for changes in the current user home directory and
/var/log:
.Pp
.Dl "$ fsw ~ /var/log"

.Sh DIAGNOSTICS
The
.Nm
utility exits 0 on success, and >0 if an error occurs.
.Sh COMPATIBILITY
This utility can be built on Apple OS X v. 10.6 or greater.

.Sh BUGS
No bugs are known.