Skip to content

Commit c885ea7

Browse files
r1cebankjasnell
r1cebank
authored andcommitted
lib: deprecate fd usage for fs.truncate(Sync)
PR-URL: #15990 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Trevor Norris <[email protected]> Reviewed-By: Colin Ihrig <[email protected]>
1 parent af49e58 commit c885ea7

File tree

5 files changed

+42
-0
lines changed

5 files changed

+42
-0
lines changed

doc/api/deprecations.md

+9
Original file line numberDiff line numberDiff line change
@@ -719,6 +719,15 @@ The internal `path._makeLong()` was not intended for public use. However,
719719
userland modules have found it useful. The internal API has been deprecated
720720
and replaced with an identical, public `path.toNamespacedPath()` method.
721721
722+
<a id="DEP0081"></a>
723+
### DEP0081: fs.truncate() using a file descriptor
724+
725+
Type: Runtime
726+
727+
`fs.truncate()` `fs.truncateSync()` usage with a file descriptor has been
728+
deprecated. Please use `fs.ftruncate()` or `fs.ftruncateSync()` to work with
729+
file descriptors.
730+
722731
723732
[`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
724733
[`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array

doc/api/fs.md

+6
Original file line numberDiff line numberDiff line change
@@ -2266,6 +2266,9 @@ Asynchronous truncate(2). No arguments other than a possible exception are
22662266
given to the completion callback. A file descriptor can also be passed as the
22672267
first argument. In this case, `fs.ftruncate()` is called.
22682268

2269+
*Note*: Passing a file descriptor is deprecated and may result in an error
2270+
being thrown in the future.
2271+
22692272
## fs.truncateSync(path[, len])
22702273
<!-- YAML
22712274
added: v0.8.6
@@ -2277,6 +2280,9 @@ added: v0.8.6
22772280
Synchronous truncate(2). Returns `undefined`. A file descriptor can also be
22782281
passed as the first argument. In this case, `fs.ftruncateSync()` is called.
22792282

2283+
*Note*: Passing a file descriptor is deprecated and may result in an error
2284+
being thrown in the future.
2285+
22802286
## fs.unlink(path, callback)
22812287
<!-- YAML
22822288
added: v0.0.2

lib/fs.js

+14
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,18 @@ const isWindows = process.platform === 'win32';
6363
const DEBUG = process.env.NODE_DEBUG && /fs/.test(process.env.NODE_DEBUG);
6464
const errnoException = util._errnoException;
6565

66+
let truncateWarn = true;
67+
68+
function showTruncateDeprecation() {
69+
if (truncateWarn) {
70+
process.emitWarning(
71+
'Using fs.truncate with a file descriptor is deprecated. Please use ' +
72+
'fs.ftruncate with a file descriptor instead.',
73+
'DeprecationWarning', 'DEP0081');
74+
truncateWarn = false;
75+
}
76+
}
77+
6678
function getOptions(options, defaultOptions) {
6779
if (options === null || options === undefined ||
6880
typeof options === 'function') {
@@ -783,6 +795,7 @@ fs.renameSync = function(oldPath, newPath) {
783795

784796
fs.truncate = function(path, len, callback) {
785797
if (typeof path === 'number') {
798+
showTruncateDeprecation();
786799
return fs.ftruncate(path, len, callback);
787800
}
788801
if (typeof len === 'function') {
@@ -808,6 +821,7 @@ fs.truncate = function(path, len, callback) {
808821
fs.truncateSync = function(path, len) {
809822
if (typeof path === 'number') {
810823
// legacy
824+
showTruncateDeprecation();
811825
return fs.ftruncateSync(path, len);
812826
}
813827
if (len === undefined) {

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

+6
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,12 @@ const filename = path.resolve(tmp, 'truncate-file.txt');
99

1010
fs.writeFileSync(filename, 'hello world', 'utf8');
1111
const fd = fs.openSync(filename, 'r+');
12+
13+
const msg = 'Using fs.truncate with a file descriptor is deprecated.' +
14+
' Please use fs.ftruncate with a file descriptor instead.';
15+
16+
17+
common.expectWarning('DeprecationWarning', msg);
1218
fs.truncate(fd, 5, common.mustCall(function(err) {
1319
assert.ok(!err);
1420
assert.strictEqual(fs.readFileSync(filename, 'utf8'), 'hello');

test/parallel/test-fs-truncate.js

+7
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@ common.refreshTmpDir();
3232

3333
let stat;
3434

35+
const msg = 'Using fs.truncate with a file descriptor is deprecated.' +
36+
' Please use fs.ftruncate with a file descriptor instead.';
37+
3538
// truncateSync
3639
fs.writeFileSync(filename, data);
3740
stat = fs.statSync(filename);
@@ -60,6 +63,10 @@ fs.ftruncateSync(fd);
6063
stat = fs.statSync(filename);
6164
assert.strictEqual(stat.size, 0);
6265

66+
// truncateSync
67+
common.expectWarning('DeprecationWarning', msg);
68+
fs.truncateSync(fd);
69+
6370
fs.closeSync(fd);
6471

6572
// async tests

0 commit comments

Comments
 (0)