lib: deprecate fd usage for fs.truncate(Sync)

PR-URL: #15990
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trevor Norris <trev.norris@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

doc/api/deprecations.md

@@ -719,6 +719,15 @@ The internal `path._makeLong()` was not intended for public use. However,
 userland modules have found it useful. The internal API has been deprecated
 and replaced with an identical, public `path.toNamespacedPath()` method.
 
+<a id="DEP0081"></a>
+### DEP0081: fs.truncate() using a file descriptor
+
+Type: Runtime
+
+`fs.truncate()` `fs.truncateSync()` usage with a file descriptor has been
+deprecated. Please use `fs.ftruncate()` or `fs.ftruncateSync()` to work with
+file descriptors.
+
 
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
 [`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array

doc/api/fs.md

@@ -2266,6 +2266,9 @@ Asynchronous truncate(2). No arguments other than a possible exception are
 given to the completion callback. A file descriptor can also be passed as the
 first argument. In this case, `fs.ftruncate()` is called.
 
+*Note*: Passing a file descriptor is deprecated and may result in an error
+being thrown in the future.
+
 ## fs.truncateSync(path[, len])
 <!-- YAML
 added: v0.8.6
@@ -2277,6 +2280,9 @@ added: v0.8.6
 Synchronous truncate(2). Returns `undefined`. A file descriptor can also be
 passed as the first argument. In this case, `fs.ftruncateSync()` is called.
 
+*Note*: Passing a file descriptor is deprecated and may result in an error
+being thrown in the future.
+
 ## fs.unlink(path, callback)
 <!-- YAML
 added: v0.0.2

lib/fs.js

@@ -63,6 +63,18 @@ const isWindows = process.platform === 'win32';
 const DEBUG = process.env.NODE_DEBUG && /fs/.test(process.env.NODE_DEBUG);
 const errnoException = util._errnoException;
 
+let truncateWarn = true;
+
+function showTruncateDeprecation() {
+  if (truncateWarn) {
+    process.emitWarning(
+      'Using fs.truncate with a file descriptor is deprecated. Please use ' +
+      'fs.ftruncate with a file descriptor instead.',
+      'DeprecationWarning', 'DEP0081');
+    truncateWarn = false;
+  }
+}
+
 function getOptions(options, defaultOptions) {
   if (options === null || options === undefined ||
       typeof options === 'function') {
@@ -783,6 +795,7 @@ fs.renameSync = function(oldPath, newPath) {
 
 fs.truncate = function(path, len, callback) {
   if (typeof path === 'number') {
+    showTruncateDeprecation();
     return fs.ftruncate(path, len, callback);
   }
   if (typeof len === 'function') {
@@ -808,6 +821,7 @@ fs.truncate = function(path, len, callback) {
 fs.truncateSync = function(path, len) {
   if (typeof path === 'number') {
     // legacy
+    showTruncateDeprecation();
     return fs.ftruncateSync(path, len);
   }
   if (len === undefined) {

test/parallel/test-fs-truncate-fd.js

@@ -9,6 +9,12 @@ const filename = path.resolve(tmp, 'truncate-file.txt');
 
 fs.writeFileSync(filename, 'hello world', 'utf8');
 const fd = fs.openSync(filename, 'r+');
+
+const msg = 'Using fs.truncate with a file descriptor is deprecated.' +
+' Please use fs.ftruncate with a file descriptor instead.';
+
+
+common.expectWarning('DeprecationWarning', msg);
 fs.truncate(fd, 5, common.mustCall(function(err) {
   assert.ok(!err);
   assert.strictEqual(fs.readFileSync(filename, 'utf8'), 'hello');

test/parallel/test-fs-truncate.js

@@ -32,6 +32,9 @@ common.refreshTmpDir();
 
 let stat;
 
+const msg = 'Using fs.truncate with a file descriptor is deprecated.' +
+            ' Please use fs.ftruncate with a file descriptor instead.';
+
 // truncateSync
 fs.writeFileSync(filename, data);
 stat = fs.statSync(filename);
@@ -60,6 +63,10 @@ fs.ftruncateSync(fd);
 stat = fs.statSync(filename);
 assert.strictEqual(stat.size, 0);
 
+// truncateSync
+common.expectWarning('DeprecationWarning', msg);
+fs.truncateSync(fd);
+
 fs.closeSync(fd);
 
 // async tests