| Copyright | (c) 2020 Composewell Technologies |
|---|---|
| License | BSD-3-Clause |
| Maintainer | streamly@composewell.com |
| Stability | pre-release |
| Portability | GHC |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Streamly.Internal.FileSystem.Event
Description
File system event notification API portable across Linux, macOS and Windows platforms.
Note that recursive directory tree watch does not work reliably on Linux (see notes in the Linux module), therefore, recursive watch API is not provided in this module. However, you can use it from the platform specific modules.
For platform specific APIs please see the following modules:
Creating a Watch
watch :: NonEmpty (Array Word8) -> Stream IO Event Source #
Start monitoring a list of directories or symbolic links to directories
for file system events. Monitoring starts from the current time onwards.
The paths are specified as UTF-8 encoded Array of Word8.
If a watch root is a symbolic link then the target of the link is watched. Fails if the watched path does not exist. If the user does not have permissions (read and execute?) on the watch root then no events are generated. No events are generated if the watch root itself is renamed or deleted.
This API watches for changes in the watch root directory only, any changes in the subdirectories of the watch root are not watched. However, on macOS the watch is always recursive, but do not rely on that behavior, it may change without notice in future. If you want to use recursive watch please use platform specific modules.
Pre-release
Handling Events
An Event generated by the file system. Use the accessor functions to examine the event.
Pre-release
getAbsPath :: Event -> Array Word8 Source #
Get the absolute path of the file system object for which the event is generated. The path is a UTF-8 encoded array of bytes.
When the watch root is a symlink the behavior is different on different platforms:
- On Linux and Windows, the absolute path returned is via the original symlink.
- On macOS the absolute path returned is via the real path of the root after resolving the symlink.
This API is subject to removal in future, to be replaced by a platform
independent getRelPath.
Pre-release
Item CRUD events
isCreated :: Event -> Bool Source #
Determine whether the event indicates creation of an object within the monitored path. This event is generated when any file system object is created.
For hard links the behavior is different on different operating systems. On
macOS hard linking does not generate a create event, it generates an
isInodeAttrsChanged event on the directory instead (see the Darwin
module). On Linux and Windows hard linking generates a create event.
Pre-release
isDeleted :: Event -> Bool Source #
Determine whether the event indicates deletion of an object within the monitored path. On Linux and Windows hard link deletion generates a delete event.
On Linux and Windows, this event does not occur when the watch root itself is deleted. On macOS it occurs on deleting the watch root when it is not a symbolic link.
See also isRootDeleted event for Linux.
Pre-release
isMoved :: Event -> Bool Source #
Determine whether the event indicates rename of an object within the monitored path. This event is generated when an object is renamed within the watched directory or if it is moved out of or in the watched directory. Moving hard links is no different than other types of objects.
Pre-release
isModified :: Event -> Bool Source #
Determine whether the event indicates modification of an object within the monitored path. This event is generated on file modification on all platforms.
On Linux and macOS this event is never generated for directories. On Windows (in recursive watch mode) this event is generated for directories as well when an object is created in or deleted from the directory.
Pre-release
Exception Conditions
isEventsLost :: Event -> Bool Source #
An event that indicates that some events before this may have been lost, therefore, we need to take some recovery action.
Pre-release