Modulestreamly-0.10.1Haskell2010

Streamly.Internal.FileSystem.Event

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:

Streamly.Internal.FileSystem.Event.Darwin
Streamly.Internal.FileSystem.Event.Linux
Streamly.Internal.FileSystem.Event.Windows

1 type
8 values

Packagestreamly-0.10.1
Exports9
LanguageHaskell2010
LicenceBSD-3-Clause
SourceEvent.hs

Creating a Watch

1 declaration

valuewatch :: NonEmpty (Array Word8) -> Stream IO Event

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

2 declarations

datadata Event

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

Pre-release

Instances3Eq, Ord, Show

Eq EventDefined in streamly-0.10.1 · Streamly.Internal.FileSystem.Event.Linux
Ord EventDefined in streamly-0.10.1 · Streamly.Internal.FileSystem.Event.Linux
Show EventDefined in streamly-0.10.1 · Streamly.Internal.FileSystem.Event.Linux

valuegetAbsPath :: Event -> Array Word8

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

valueisCreated :: Event -> Bool

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

valueisDeleted :: Event -> Bool

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

valueisMoved :: Event -> Bool

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

valueisModified :: Event -> Bool

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

valueisEventsLost :: Event -> Bool

An event that indicates that some events before this may have been lost, therefore, we need to take some recovery action.

Pre-release

Debugging

valueshowEvent :: Event -> String

Convert an Event record to a String representation. Note that the output of this function may be different on different platforms because it may contain platform specific details.

Internal