Skip to content
This repository has been archived by the owner on Apr 22, 2023. It is now read-only.

Commit

Permalink
Browse files Browse the repository at this point in the history
doc: Stability and Caveats for fs.watch/watchFile
  • Loading branch information
isaacs committed Mar 4, 2012
1 parent f70be20 commit 2e48737
Showing 1 changed file with 36 additions and 2 deletions.
38 changes: 36 additions & 2 deletions doc/api/fs.markdown
Expand Up @@ -391,6 +391,8 @@ The synchronous version of `fs.writeFile`.

## fs.watchFile(filename, [options], listener)

Stability: 2 - Unstable. Use fs.watch instead, if available.

Watch for changes on `filename`. The callback `listener` will be called each
time the file is accessed.

Expand All @@ -417,10 +419,14 @@ you need to compare `curr.mtime` and `prev.mtime`.

## fs.unwatchFile(filename)

Stability: 2 - Unstable. Use fs.watch instead, if available.

Stop watching for changes on `filename`.

## fs.watch(filename, [options], listener)

Stability: 2 - Unstable. Not available on all platforms.

Watch for changes on `filename`, where `filename` is either a file or a
directory. The returned object is a [fs.FSWatcher](#fs_class_fs_fswatcher).

Expand All @@ -433,8 +439,36 @@ The listener callback gets two arguments `(event, filename)`. `event` is either
'rename' or 'change', and `filename` is the name of the file which triggered
the event.

***Warning:***
Providing `filename` argument in the callback is not supported
### Caveats

<!--type=misc-->

The `fs.watch` API is not 100% consistent across platforms, and is
unavailable in some situations.

#### Availability

<!--type=misc-->

This feature depends on the underlying operating system providing a way
to be notified of filesystem changes.

* On Linux systems, this uses `inotify`.
* On BSD systems (including OS X), this uses `kqueue`.
* On SunOS systems (including Solaris and SmartOS), this uses `event ports`.
* On Windows systems, this feature depends on `ReadDirectoryChangesW`.

If the underlying functionality is not available for some reason, then
`fs.watch` will not be able to function. You can still use
`fs.watchFile`, which uses stat polling, but it is slower and less
reliable.

#### Filename Argument

<!--type=misc-->

When watching a directory,
providing `filename` argument in the callback is not supported
on every platform (currently it's only supported on Linux and Windows). Even
on supported platforms `filename` is not always guaranteed to be provided.
Therefore, don't assume that `filename` argument is always provided in the
Expand Down

0 comments on commit 2e48737

Please sign in to comment.