fs: add file descriptor support to *File() funcs

These changes affect the following functions and their synchronous
counterparts:

 * fs.readFile()
 * fs.writeFile()
 * fs.appendFile()

If the first parameter is a uint32, it is treated as a file descriptor.
In all other cases, the original implementation is used to ensure
backwards compatibility. File descriptor ownership is never taken from
the user.

The documentation was adjusted to reflect these API changes. A note was
added to make the user aware of file descriptor ownership and the
conditions under which a file descriptor can be used by each of these
functions.

Tests were extended to test for file descriptor parameters under the
conditions noted in the relevant documentation.

PR-URL: https://github.com/nodejs/node/pull/3163
Reviewed-By: Trevor Norris <trev.norris@gmail.com>

1 files changed, 32 insertions, 1 deletions

diff --git a/test/parallel/test-fs-append-file.js b/test/parallel/test-fs-append-file.js
index b20323bd14..01742aa6f8 100644
--- a/test/parallel/test-fs-append-file.js
+++ b/test/parallel/test-fs-append-file.js
@@ -92,11 +92,42 @@ fs.appendFile(filename4, n, { mode: m }, function(e) {
   });
 });
 
+// test that appendFile accepts file descriptors
+var filename5 = join(common.tmpDir, 'append5.txt');
+fs.writeFileSync(filename5, currentFileData);
+
+fs.open(filename5, 'a+', function(e, fd) {
+  if (e) throw e;
+
+  ncallbacks++;
+
+  fs.appendFile(fd, s, function(e) {
+    if (e) throw e;
+
+    ncallbacks++;
+
+    fs.close(fd, function(e) {
+      if (e) throw e;
+
+      ncallbacks++;
+
+      fs.readFile(filename5, function(e, buffer) {
+        if (e) throw e;
+
+        ncallbacks++;
+        assert.equal(Buffer.byteLength(s) + currentFileData.length,
+                     buffer.length);
+      });
+    });
+  });
+});
+
 process.on('exit', function() {
-  assert.equal(8, ncallbacks);
+  assert.equal(12, ncallbacks);
 
   fs.unlinkSync(filename);
   fs.unlinkSync(filename2);
   fs.unlinkSync(filename3);
   fs.unlinkSync(filename4);
+  fs.unlinkSync(filename5);
 });