Watch configuration, used to specify the events of interest and the behavior of the watch.

Pre-release

The default configuration settings are:

• setFollowSymLinks True
• setUnwatchMoved True
• setOneShot False
• setOnlyDir False
• setWhenExists AddIfExists

The tunable events enabled by default are:

• setCreated True
• setDeleted True
• setMovedFrom True
• setMovedTo True
• setModified True

Pre-release

Watch the whole directory tree recursively instead of watching just one level of directory.

default: False

Pre-release

If the pathname to be watched is a symbolic link then watch the target of the symbolic link instead of the symbolic link itself.

Note that the path location in the events is through the original symbolic link path rather than the resolved path.

default: True

Pre-release

If an object moves out of the directory being watched then stop watching it.

default: True

Pre-release

Watch the object only for one event and then remove it from the watch.

default: False

Pre-release

Watch the object only if it is a directory. This provides a race-free way to ensure that the watched object is a directory.

default: False

Pre-release

What to do if a watch already exists when openWatch or addToWatch is called for a path.

Pre-release

When adding a new path to the watch, specify what to do if a watch already exists on that path.

default: FailIfExists

Pre-release

Report when the watched path itself gets deleted.

default: True

Pre-release

Report when the watched root path itself gets renamed.

default: True

Pre-release

Report when the watched root path itself gets deleted or renamed.

default: True

Pre-release

Report when the metadata e.g. owner, permission modes, modifications times of an object changes.

default: True

Pre-release

Report when a file is accessed.

default: True

Pre-release

Report when a file is opened.

default: True

Pre-release

Report when a file that was opened for writes is closed.

default: True

Pre-release

Report when a file that was opened for not writing is closed.

default: True

Pre-release

Report when a file is created.

default: True

Pre-release

Report when a file is deleted.

default: True

Pre-release

Report the source of a move.

default: True

Pre-release

Report the target of a move.

default: True

Pre-release

Report when a file is modified.

default: True

Pre-release

Set all tunable events True or False. Equivalent to setting:

• setRootDeleted
• setRootMoved
• setAttrsModified
• setAccessed
• setOpened
• setWriteClosed
• setNonWriteClosed
• setCreated
• setDeleted
• setMovedFrom
• setMovedTo
• setModified

Pre-release

Same as watchWith using defaultConfig and non-recursive mode.

>>> watch = watchWith id

Pre-release

Same as watchWith using defaultConfig and recursive mode.

>>> watchRecursive = watchWith (setRecursiveMode True)

See watchWith for pitfalls and bugs when using recursive watch on Linux.

Pre-release

Start monitoring a list of file system paths for file system events with the supplied configuration operation over the defaultConfig. The paths could be files or directories. When recursive mode is set and the path is a directory, the whole directory tree under it is watched recursively. Monitoring starts from the current time onwards. The paths are specified as UTF-8 encoded Array of Word8.

Non-existing Paths: the API fails if a watch is started on a non-exsting path.

Performance: Note that recursive watch on a large directory tree could be expensive. When starting a watch, the whole tree must be read and watches are started on each directory in the tree. The initial time to start the watch as well as the memory required is proportional to the number of directories in the tree.

Bugs: When new directories are created under the tree they are added to the watch on receiving the directory create event. However, the creation of a dir and adding a watch for it is not atomic. The implementation takes care of this and makes sure that watches are added for all directories. However, In the mean time, the directory may have received more events which may get lost. Handling of any such lost events is yet to be implemented.

See the Linux inotify man page for more details.

watchwith
     (setFollowSymLinks True . setUnwatchMoved False)
     [Array.fromList "dir"]

Pre-release

addToWatch cfg watch root subpath adds subpath to the list of paths being monitored under root via the watch handle watch. root must be an absolute path and subpath must be relative to root.

Pre-release

Remove an absolute root path from a Watch, if a path was moved after adding you need to provide the original path which was used to add the Watch.

Pre-release

An Event generated by the file system. Use the accessor functions to examine the event.

Pre-release

Get the watch root corresponding to the Event.

Note that if a path was moved after adding to the watch, this will give the original path and not the new path after moving.

TBD: we can possibly update the watch root on a move self event.

Pre-release

Get the file system object path for which the event is generated, relative to the watched root. The path is a "/" separated array of bytes.

Pre-release

Get the absolute file system object path for which the event is generated.

When the watch root is a symlink, the absolute path returned is via the original symlink and not through the resolved path.

Pre-release

Cookie is set when a rename occurs. The cookie value can be used to connect the isMovedFrom and isMovedTo events, if both the events belong to the same move operation then they will have the same cookie value.

Pre-release

Determine whether the event indicates a change of path of the monitored object itself. Note that the object may become unreachable or deleted after a change of path.

Occurs only for a watched path

Pre-release

A path was removed from the watch explicitly using removeFromWatch or automatically (file was deleted, or filesystem was unmounted).

Note that in recursive watch mode all the subdirectories are watch roots, therefore, they will all generate this event.

Occurs only for a watched path

Pre-release

Watched file/directory was itself deleted. (This event also occurs if an object is moved to another filesystem, since mv(1) in effect copies the file to the other filesystem and then deletes it from the original filesystem.) In addition, an isRootUnwatched event will subsequently be generated for the watch descriptor.

Note that in recursive watch mode all the subdirectories are watch roots, therefore, they will all generate this event.

Occurs only for a watched path

Pre-release

Watched file/directory was itself moved within the file system.

Note that in recursive watch mode all the subdirectories are watch roots, therefore, they will all generate this event.

Occurs only for a watched path

Pre-release

Filesystem containing watched object was unmounted. In addition, an isRootUnwatched event will subsequently be generated for the watch descriptor.

Occurs only for a watched path

Pre-release

Determine whether the event indicates inode metadata change for an object contained within the monitored path.

Metadata change may include, permissions (e.g., chmod(2)), timestamps (e.g., utimensat(2)), extended attributes (setxattr(2)), link count (since Linux 2.6.25; e.g., for the target of link(2) and for unlink(2)), and user/group ID (e.g., chown(2)).

Can occur for watched path or a file inside it

Pre-release

File was accessed (e.g. read, execve).

Occurs only for a file inside the watched directory

Pre-release

File or directory was opened.

Occurs only for a file inside the watched directory

Pre-release

File opened for writing was closed.

Occurs only for a file inside the watched directory

Pre-release

File or directory opened for read but not write was closed.

Can occur for watched path or a file inside it

Pre-release

File/directory created in watched directory (e.g., open(2) O_CREAT, mkdir(2), link(2), symlink(2), bind(2) on a UNIX domain socket).

Occurs only for an object inside the watched directory

Pre-release

File/directory deleted from watched directory.

Occurs only for an object inside the watched directory

Pre-release

Generated for the original path when an object is moved from under a monitored directory.

Occurs only for an object inside the watched directory

Pre-release

Generated for the new path when an object is moved under a monitored directory.

Occurs only for an object inside the watched directory

Pre-release

Generated for a path that is moved from or moved to the monitored directory.

>>> isMoved ev = isMovedFrom ev || isMovedTo ev

Occurs only for an object inside the watched directory

Pre-release

Determine whether the event indicates modification of an object within the monitored path. This event is generated only for files and not directories.

Occurs only for an object inside the watched directory

Pre-release

Determine whether the event is for a directory path.

Pre-release

Event queue overflowed (WD is invalid for this event) and we may have lost some events.. The user application must scan everything under the watched paths to know the current state.

Pre-release

Convert an Event record to a String representation.