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

doc: Stability and Caveats for

  • 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 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 instead, if available.

Stop watching for changes on `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.

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


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

#### Availability


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
`` will not be able to function. You can still use
`fs.watchFile`, which uses stat polling, but it is slower and less

#### Filename Argument


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.