fs: add access() and accessSync()

fs.exists() and fs.existsSync() do not follow the typical
error first callback convention. access() and accessSync()
are added as alternatives in this commit.

Fixes: https://github.com/joyent/node/pull/8714
PR-URL: https://github.com/iojs/io.js/pull/114
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Domenic Denicola <domenic@domenicdenicola.com>

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown
index c6bfa2456b..17bc55ca5e 100644
--- a/doc/api/fs.markdown
+++ b/doc/api/fs.markdown
@@ -656,10 +656,43 @@ 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.exists()` will be deprecated.
+
 ## fs.existsSync(path)
 
 Synchronous version of `fs.exists`.
 
+`fs.existsSync()` will be deprecated.
+
+## fs.access(path[, mode], callback)
+
+Tests a user's permissions for the file specified by `path`. `mode` is an
+optional integer that specifies the accessibility checks to be performed. The
+following constants define the possible values of `mode`. It is possible to
+create a mask consisting of the bitwise OR of two or more values.
+
+- `fs.F_OK` - File is visible to the calling process. This is useful for
+determining if a file exists, but says nothing about `rwx` permissions.
+Default if no `mode` is specified.
+- `fs.R_OK` - File can be read by the calling process.
+- `fs.W_OK` - File can be written by the calling process.
+- `fs.X_OK` - File can be executed by the calling process. This has no effect
+on Windows (will behave like `fs.F_OK`).
+
+The final argument, `callback`, is a callback function that is invoked with
+a possible error argument. If any of the accessibility checks fail, the error
+argument will be populated. The following example checks if the file
+`/etc/passwd` can be read and written by the current process.
+
+    fs.access('/etc/passwd', fs.R_OK | fs.W_OK, function(err) {
+      util.debug(err ? 'no access!' : 'can read/write');
+    });
+
+## fs.accessSync(path[, mode])
+
+Synchronous version of `fs.access`. This throws if any accessibility checks
+fail, and does nothing otherwise.
+
 ## Class: fs.Stats
 
 Objects returned from `fs.stat()`, `fs.lstat()` and `fs.fstat()` and their