Manual page

Tcl fswatch extension

fswatch - Tcl library for filesystem notifications


Synopsis

package require Tcl 8.5
package require fswatch 2.0

fswatch create callback
fswatch add channelId ?-replace? path flags
fswatch remove channelId ?watchId ...?
fswatch close channelId
fswatch info channelId ?watchId ...?


Description

The fswatch package provides a command to set up notifications about filesystem events.

fswatch create callback
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:
chan
The channelId.
watch
The watchId.
path
The path associated with the watchId.
event
The type of event. See events below.
isdir
A boolean indicating if the event is related to a direcory.
cookie
An integer to tie related events together (only for movedfrom and movedto events).
name
The name of the affected file or directory (if applicable).
fswatch add channelId ?-replace? path flags
Add a target path to an fswatch channelId. The command returns a watchId. The flags argument is a list specifying which events should be reported. See events below. If the path was already being watched, the specified events are added to the existing list, unless the -replace option is present.
fswatch remove channelId ?watchId ...?
Remove target paths from an fswatch channelId.
fswatch close channelId
Closes an fswatch channelId.
fswatch info channelId ?watchId ...?
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.

Events

The following event types may be specified in the add command, and may also be reported to the callback.

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