Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
Browse files

doc: Stability and Caveats for fs.watch/watchFile

  • Loading branch information...
isaacs committed Mar 4, 2012
1 parent f70be20 commit 2e487379adabe09b19e92e4f4ecb5bc143679aca
Showing with 36 additions and 2 deletions.
  1. +36 −2 doc/api/fs.markdown
@@ -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.

@@ -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).

@@ -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

0 comments on commit 2e48737

Please sign in to comment.
You can’t perform that action at this time.