diff options
author | isaacs <i@izs.me> | 2012-03-04 04:23:31 +0400 |
---|---|---|
committer | isaacs <i@izs.me> | 2012-03-04 05:04:02 +0400 |
commit | 2e487379adabe09b19e92e4f4ecb5bc143679aca (patch) | |
tree | 36a7e94a7cb30561fef55c63b54e8625ccfd5b03 /doc/api | |
parent | f70be203e4abf05bc401e0eedc8646ac4da8be09 (diff) |
doc: Stability and Caveats for fs.watch/watchFile
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/fs.markdown | 38 |
1 files changed, 36 insertions, 2 deletions
diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 2c7f43674f7..822e03af2f2 100644 --- a/doc/api/fs.markdown +++ b/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 |