doc: add warning to fs.exists() documentation

Warn against the open-if-exists anti-pattern, it's susceptible to
race conditions.

1 files changed, 7 insertions, 0 deletions

diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown
index 129f3c5767..f940e6364f 100644
--- a/doc/api/fs.markdown
+++ b/doc/api/fs.markdown
@@ -595,6 +595,13 @@ Then call the `callback` argument with either true or false.  Example:
       util.debug(exists ? "it's there" : "no passwd!");
     });
 
+`fs.exists()` is an anachronism and exists only for historical reasons.
+There should almost never be a reason to use it in your own code.
+
+In particular, checking if a file exists before opening it is an anti-pattern
+that leaves you vulnerable to race conditions: another process may remove the
+file between the calls to `fs.exists()` and `fs.open()`.  Just open the file
+and handle the error when it's not there.
 
 ## fs.existsSync(path)