watch method Null safety

Stream<FileSystemEvent> watch (
  1. {int events: FileSystemEvent.all,
  2. bool recursive: false}
)

Start watching the FileSystemEntity for changes.

The implementation uses platform-dependent event-based APIs for receiving file-system notifications, thus behavior depends on the platform.

  • Windows: Uses ReadDirectoryChangesW. The implementation only supports watching directories. Recursive watching is supported.
  • Linux: Uses inotify. The implementation supports watching both files and directories. Recursive watching is not supported. Note: When watching files directly, delete events might not happen as expected.
  • OS X: Uses FSEvents. The implementation supports watching both files and directories. Recursive watching is supported.

The system will start listening for events once the returned Stream is being listened to, not when the call to watch is issued.

The returned value is an endless broadcast Stream, that only stops when one of the following happens:

  • The Stream is canceled, e.g. by calling cancel on the StreamSubscription.
  • The FileSystemEntity being watched, is deleted.
  • System Watcher exits unexpectedly. e.g. On Windows this happens when buffer that receive events from ReadDirectoryChangesW overflows.

Use events to specify what events to listen for. The constants in FileSystemEvent can be or'ed together to mix events. Default is FileSystemEvent.ALL.

A move event may be reported as seperate delete and create events.

Implementation

Stream<FileSystemEvent> watch(
    {int events: FileSystemEvent.all, bool recursive: false}) {
  // FIXME(bkonyi): find a way to do this using the raw path.
  final String trimmedPath = _trimTrailingPathSeparators(path);
  final IOOverrides? overrides = IOOverrides.current;
  if (overrides == null) {
    return _FileSystemWatcher._watch(trimmedPath, events, recursive);
  }
  return overrides.fsWatch(trimmedPath, events, recursive);
}