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>

5 files changed, 135 insertions, 2 deletions

diff --git a/test/parallel/test-fs-append-file-sync.js b/test/parallel/test-fs-append-file-sync.js
index 42e0790e1f..4c5ae870ec 100644
--- a/test/parallel/test-fs-append-file-sync.js
+++ b/test/parallel/test-fs-append-file-sync.js
@@ -66,6 +66,19 @@ var fileData4 = fs.readFileSync(filename4);
 assert.equal(Buffer.byteLength('' + num) + currentFileData.length,
              fileData4.length);
 
+// test that appendFile accepts file descriptors
+var filename5 = join(common.tmpDir, 'append-sync5.txt');
+fs.writeFileSync(filename5, currentFileData);
+
+var filename5fd = fs.openSync(filename5, 'a+', 0o600);
+fs.appendFileSync(filename5fd, data);
+fs.closeSync(filename5fd);
+
+var fileData5 = fs.readFileSync(filename5);
+
+assert.equal(Buffer.byteLength(data) + currentFileData.length,
+             fileData5.length);
+
 //exit logic for cleanup
 
 process.on('exit', function() {
@@ -73,4 +86,5 @@ process.on('exit', function() {
   fs.unlinkSync(filename2);
   fs.unlinkSync(filename3);
   fs.unlinkSync(filename4);
+  fs.unlinkSync(filename5);
 });
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);
 });
diff --git a/test/parallel/test-fs-readfile-fd.js b/test/parallel/test-fs-readfile-fd.js
new file mode 100644
index 0000000000..fc63d480ab
--- /dev/null
+++ b/test/parallel/test-fs-readfile-fd.js
@@ -0,0 +1,47 @@
+'use strict';
+var common = require('../common');
+var assert = require('assert');
+
+var path = require('path'),
+    fs = require('fs'),
+    fn = path.join(common.fixturesDir, 'empty.txt');
+
+tempFd(function(fd, close) {
+  fs.readFile(fd, function(err, data) {
+    assert.ok(data);
+    close();
+  });
+});
+
+tempFd(function(fd, close) {
+  fs.readFile(fd, 'utf8', function(err, data) {
+    assert.strictEqual('', data);
+    close();
+  });
+});
+
+tempFdSync(function(fd) {
+  assert.ok(fs.readFileSync(fd));
+});
+
+tempFdSync(function(fd) {
+  assert.strictEqual('', fs.readFileSync(fd, 'utf8'));
+});
+
+function tempFd(callback) {
+  fs.open(fn, 'r', function(err, fd) {
+    if (err) throw err;
+
+    callback(fd, function() {
+      fs.close(fd, function(err) {
+        if (err) throw err;
+      });
+    });
+  });
+}
+
+function tempFdSync(callback) {
+  var fd = fs.openSync(fn, 'r');
+  callback(fd);
+  fs.closeSync(fd);
+}
diff --git a/test/parallel/test-fs-write-file-sync.js b/test/parallel/test-fs-write-file-sync.js
index 37373404da..72c0a2b19b 100644
--- a/test/parallel/test-fs-write-file-sync.js
+++ b/test/parallel/test-fs-write-file-sync.js
@@ -47,6 +47,18 @@ assert.equal('abc', content);
 
 assert.equal(mode, fs.statSync(file2).mode & mode);
 
+// Test writeFileSync with file descriptor
+var file3 = path.join(common.tmpDir, 'testWriteFileSyncFd.txt');
+
+var fd = fs.openSync(file3, 'w+', mode);
+fs.writeFileSync(fd, '123');
+fs.closeSync(fd);
+
+content = fs.readFileSync(file3, {encoding: 'utf8'});
+assert.equal('123', content);
+
+assert.equal(mode, fs.statSync(file3).mode & 0o777);
+
 // Verify that all opened files were closed.
 assert.equal(0, openCount);
 
diff --git a/test/parallel/test-fs-write-file.js b/test/parallel/test-fs-write-file.js
index 9ff3b3f39a..a29e841ea2 100644
--- a/test/parallel/test-fs-write-file.js
+++ b/test/parallel/test-fs-write-file.js
@@ -69,11 +69,40 @@ fs.writeFile(filename3, n, { mode: m }, function(e) {
   });
 });
 
+// test that writeFile accepts file descriptors
+var filename4 = join(common.tmpDir, 'test4.txt');
+var buf = new Buffer(s, 'utf8');
+
+fs.open(filename4, 'w+', function(e, fd) {
+  if (e) throw e;
+
+  ncallbacks++;
+
+  fs.writeFile(fd, s, function(e) {
+    if (e) throw e;
+
+    ncallbacks++;
+
+    fs.close(fd, function(e) {
+      if (e) throw e;
+
+      ncallbacks++;
+
+      fs.readFile(filename4, function(e, buffer) {
+        if (e) throw e;
+
+        ncallbacks++;
+        assert.equal(Buffer.byteLength(s), buffer.length);
+      });
+    });
+  });
+});
 
 process.on('exit', function() {
-  assert.equal(6, ncallbacks);
+  assert.equal(10, ncallbacks);
 
   fs.unlinkSync(filename);
   fs.unlinkSync(filename2);
   fs.unlinkSync(filename3);
+  fs.unlinkSync(filename4);
 });