<h1>Tcl fswatch extension</h1>

<p>fswatch - Tcl library for filesystem notifications

<hr>

<h2>Synopsis</h2>

<p>
package require <b>Tcl 8.5</b><br>
package require <b>fswatch 2.0</b><br>
<p>
[#1|<b>fswatch</b> <b>create</b> <i>callback</i>]<br>
[#2|<b>fswatch</b> <b>add</b> <i>channelId</i> ?<b>-replace</b>? <i>path</i> <i>flags</i>]<br>
[#3|<b>fswatch</b> <b>remove</b> <i>channelId</i> ?<i>watchId</i> <i>...</i>?]<br>
[#4|<b>fswatch</b> <b>close</b> <i>channelId</i>]<br>
[#5|<b>fswatch</b> <b>info</b> <i>channelId</i> ?<i>watchId</i> ...?]<br>

<hr>

<h2>Description</h2>

The <b>fswatch</b> package provides a command to set up
notifications about filesystem events.
<dl>
<dt><a <b>create</b> <i>callback</i>
<dd>Create an fswatch channelId. The command returns a channelId to be used in
other fswatch subcommands.
When any watch within the channelId fires, the callback will be called with
one additional argument: A dict describing the event that caused the watch to
fire.
The dict contains the following items:
<dl>
<dt><em>chan</em>
<dd>The channelId.
<dt><em>watch</em>
<dd>The watchId.
<dt><em>path</em>
<dd>The path associated with the watchId.
<dt><em>event</em>
<dd>The type of event. See <b>events</b> below.
<dt><em>isdir</em>
<dd>A boolean indicating if the event is related to a direcory.
<dt><em>cookie</em>
<dd>An integer to tie related events together (only for
movedfrom and movedto events).
<dt><em>name</em>
<dd>The name of the affected file or directory (if applicable).
</dl>
<dt><a <b>add</b> <i>channelId</i> ?<b>-replace</b>? <i>path</i> <i>flags</i>
<dd>Add a target path to an fswatch channelId. The command returns a watchId. The
<i>flags</i> argument is a list specifying which events should be reported. See
<b>events</b> below.
If the path was already being watched, the specified events are added to the
existing list, unless the <b>-replace</b> option is present.
<dt><a <b>remove</b> <i>channelId</i> ?<i>watchId</i> <i>...</i>?
<dd>Remove target paths from an fswatch channelId.
<dt><a <b>close</b> <i>channelId</i>
<dd>Closes an fswatch channelId.
<dt><a <b>info</b> <i>channelId</i> ?<i>watchId</i> ...?
<dd>Return information about active watchIds as a dict. The dict's keys are
the requested watchId (or all watchIds if the optional arguments were omitted)
and the values a list of path and event types each.
</dl>

<h2>Events</h2>

The following event types may be specified in the <b>add</b> command, and may
also be reported to the <i>callback</i>.
<dl>
<dt><em>access</em>
<dd>File is accessed.
<dt><em>modify</em>
<dd>File is modified.
<dt><em>attrib</em>
<dd>Metadata changes.
<dt><em>closewrite</em>
<dd>File opened for writing is closed.
<dt><em>closenowrite</em>
<dd>File or directory not opened for writing is closed.
<dt><em>open</em>
<dd>File or directory is opened.
<dt><em>movedfrom</em>
<dd>Generated for the directory containing the old filename
when a file is renamed.
<dt><em>movedto</em>
<dd>Generated for the directory containing the new filename
when a file is renamed.
<dt><em>create</em>
<dd>File/directory created in watched directory.
<dt><em>delete</em>
<dd>File/directory deleted from watched directory.
<dt><em>deleteself</em>
<dd>Watched file/directory is itself deleted.
<dt><em>moveself</em>
<dd>Watched file/directory is itself moved.
</dl>
A few shorthand names are available for some combinations of events. These
will never appear in the dict provided to the <i>callback</i>.
<dl>
<dt><em>close</em>
<dd>Shorthand for {closewrite closenowrite}.
<dt><em>move</em>
<dd>Shorthand for {movedfrom movedto}.
<dt><em>allevents</em>
<dd>Shorthand for monitoring all watchable events.
</dl>
Some additional names may be included in the <i>flags</i> argument to control
how the other events should be handled.
<dl>
<dt><em>oneshot</em>
<dd>Monitor the filesystem object corresponding to pathname
for one event, then remove from watch list.
<dt><em>exclunlink</em>
<dd>Don't generate events for children after they have been
unlinked from the watched directory.
</dl>
Finally, the dict provided to the <i>callback</i> can report a number of
special events.
<dl>
<dt><em>unmount</em>
<dd>Filesystem containing watched object is unmounted.
<dt><em>qoverflow</em>
<dd>Event queue overflowed
<dt><em>ignored</em>
<dd>Watch is removed.
</dl>