doc: deprecation note for fs.truncate(Sync)

nodejs · r1cebank · Oct 6, 2017 · Oct 6, 2017 · Oct 11, 2017 · 2ff66b98b969c98d0495de64b3b3ffa1c2300cc8
commit 2ff66b98b969c98d0495de64b3b3ffa1c2300cc8
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -719,6 +719,17 @@ 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="DEP00XX"></a>
+### DEP0081: fs.truncate()
+
+Type: Runtime
+
+`fs.truncate()` `fs.truncateSync()` usage with
+a file descriptor has been deprecated.
+
+*Note*: 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
@@ -2268,6 +2268,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
@@ -2279,6 +2282,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
@@ -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', 'DEP00XX');
+    truncateWarn = false;
+  }
+}
+
 function getOptions(options, defaultOptions) {
   if (options === null || options === undefined ||
       typeof options === 'function') {
@@ -783,10 +795,7 @@ fs.renameSync = function(oldPath, newPath) {
 
 fs.truncate = function(path, len, callback) {
   if (typeof path === 'number') {
-    process.emitWarning(
-      'Using fs.truncate with file descriptor deprecated. In the future, ' +
-      'use fs.ftruncate with file descriptor',
-      'DeprecationWarning', 'DEP00XX');
+    showTruncateDeprecation();
     return fs.ftruncate(path, len, callback);
   }
   if (typeof len === 'function') {
@@ -812,10 +821,7 @@ fs.truncate = function(path, len, callback) {
 fs.truncateSync = function(path, len) {
   if (typeof path === 'number') {
     // legacy
-    process.emitWarning(
-      'Using fs.truncate with file descriptor deprecated. In the future, ' +
-      'use fs.ftruncate with file descriptor',
-      'DeprecationWarning', 'DEP00XX');
+    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
@@ -9,9 +9,11 @@ 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 file descriptor deprecated.' +
-            ' In the future, ' +
-            'use fs.ftruncate with file descriptor';
+
+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);

diff --git a/test/parallel/test-fs-truncate.js b/test/parallel/test-fs-truncate.js
@@ -32,9 +32,8 @@ common.refreshTmpDir();
 
 let stat;
 
-const msg = 'Using fs.truncate with file descriptor deprecated.' +
-            ' In the future, ' +
-            'use fs.ftruncate with file descriptor';
+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);