Home

The fswatch command


Synopsis

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


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:
watch
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 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.
fswatch remove channelId ?watchId ...?
Remove target paths from an fswatch channelId.
fswatch close channelId
Closes an fswatch channelId.

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.

onlydir
Watch pathname only if it is a directory.
dontfollow
Don't dereference pathname if it is a symbolic link.
exclunlink
Don't generate events for children after they have been unlinked from the watched directory.
maskadd
If a watch instance already exists for the filesystem object corresponding to pathname, add the events in mask to the watch mask instead of replacing the mask.
oneshot

Monitor the filesystem object corresponding to pathname for one event, then remove from watch list.

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.