From c885ea727da7ffd66deb5a775a0d1fb40f14a329 Mon Sep 17 00:00:00 2001
From: r1cebank <siyuangao@gmail.com>
Date: Fri, 6 Oct 2017 11:06:35 -0700
Subject: [PATCH] lib: deprecate fd usage for fs.truncate(Sync)

PR-URL: https://github.com/nodejs/node/pull/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              |  9 +++++++++
 doc/api/fs.md                        |  6 ++++++
 lib/fs.js                            | 14 ++++++++++++++
 test/parallel/test-fs-truncate-fd.js |  6 ++++++
 test/parallel/test-fs-truncate.js    |  7 +++++++
 5 files changed, 42 insertions(+)

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 76165638839e38..2a21d645b6e46c 100644
--- a/doc/api/deprecations.md
+++ b/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
diff --git a/doc/api/fs.md b/doc/api/fs.md
index 997a99a612402d..1d131ef5413e37 100644
--- a/doc/api/fs.md
+++ b/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
diff --git a/lib/fs.js b/lib/fs.js
index b7a2bbba0ce82e..5668540486a8fa 100644
--- a/lib/fs.js
+++ b/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) {
diff --git a/test/parallel/test-fs-truncate-fd.js b/test/parallel/test-fs-truncate-fd.js
index 526612870d9f73..6776dfb2668f48 100644
--- a/test/parallel/test-fs-truncate-fd.js
+++ b/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');
diff --git a/test/parallel/test-fs-truncate.js b/test/parallel/test-fs-truncate.js
index a56a1a054ca718..4119d53c4f8d95 100644
--- a/test/parallel/test-fs-truncate.js
+++ b/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