From 2e54b5aa928e3b228f3026c2df6a9b05b8ca2e7f Mon Sep 17 00:00:00 2001 From: Sakthipriyan Vairamani Date: Sat, 27 Aug 2016 15:51:52 +0530 Subject: [PATCH 1/3] test: make sure over truncation of file zero fills If the file is over truncated, then the rest of the file should be filled with zeroes. These tests ensure the same. --- test/parallel/test-fs-truncate.js | 40 +++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/test/parallel/test-fs-truncate.js b/test/parallel/test-fs-truncate.js index ab0148a2461f70..442038eeb50a51 100644 --- a/test/parallel/test-fs-truncate.js +++ b/test/parallel/test-fs-truncate.js @@ -106,3 +106,43 @@ function testFtruncate(cb) { }); }); } + + +// Make sure if the size of the file is smaller than the length then it is +// filled with zeroes. + +{ + const file1 = path.resolve(tmp, 'truncate-file-1.txt'); + fs.writeFileSync(file1, 'Hi'); + fs.truncateSync(file1, 4); + assert(fs.readFileSync(file1).equals(Buffer.from('Hi\u0000\u0000'))); +} + +{ + const file2 = path.resolve(tmp, 'truncate-file-2.txt'); + fs.writeFileSync(file2, 'Hi'); + const fd = fs.openSync(file2, 'r+'); + process.on('exit', () => fs.closeSync(fd)); + fs.ftruncateSync(fd, 4); + assert(fs.readFileSync(file2).equals(Buffer.from('Hi\u0000\u0000'))); +} + +{ + const file3 = path.resolve(tmp, 'truncate-file-3.txt'); + fs.writeFileSync(file3, 'Hi'); + fs.truncate(file3, 4, common.mustCall(function(err) { + assert.ifError(err); + assert(fs.readFileSync(file3).equals(Buffer.from('Hi\u0000\u0000'))); + })); +} + +{ + const file4 = path.resolve(tmp, 'truncate-file-4.txt'); + fs.writeFileSync(file4, 'Hi'); + const fd = fs.openSync(file4, 'r+'); + process.on('exit', () => fs.closeSync(fd)); + fs.ftruncate(fd, 4, common.mustCall(function(err) { + assert.ifError(err); + assert(fs.readFileSync(file4).equals(Buffer.from('Hi\u0000\u0000'))); + })); +} From 7c20ba9a99107c525aa0341303b2accbb9d6cc2d Mon Sep 17 00:00:00 2001 From: Sakthipriyan Vairamani Date: Sat, 27 Aug 2016 15:53:14 +0530 Subject: [PATCH 2/3] doc: improve fs.truncate functions' documentation The default value of the `len` parameter is zero and it is included in the documenetation. This patch also has examples of how `ftruncate` can be used. --- doc/api/fs.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 5 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index d7297abfb0ce2c..679269edefcb92 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -739,19 +739,59 @@ added: v0.8.6 --> * `fd` {Integer} -* `len` {Integer} +* `len` {Integer} default = `0` * `callback` {Function} Asynchronous ftruncate(2). No arguments other than a possible exception are given to the completion callback. +If the file referred to by the file descriptor was larger than `len` bytes, only +the first `len` bytes will be retained in the file. + +For example, the following program retains only the first four bytes of the file + +```js +console.log(fs.readFileSync('temp.txt', 'utf8'); + // prints Node.js + +// get the file descriptor of the file to be truncated +const fd = fs.openSync('temp.txt', 'r+'); + +// truncate the file to first four bytes +fs.ftruncate(fd, 4, (err) => { + assert.ifError(err); + console.log(fs.readFileSync('temp.txt', 'utf8')); +}); + // prints Node +``` + +If the file previously was shorter than `len` bytes, it is extended, and the +extended part is filled with null bytes ('\0'). For example, + +```js +fs.readFileSync('temp.txt', 'utf-8'); + // prints Node.js + +// get the file descriptor of the file to be truncated +const fd = fs.openSync('temp.txt', 'r+'); + +// truncate the file to 10 bytes, whereas the actual size is 7 bytes +fs.ftruncate(fd, 10, (err) => { + assert.ifError(!err); + console.log(fs.readFileSync('temp.txt')); +}); + // prints +``` + +The last three bytes are zeroes, to compensate the over-truncation. + ## fs.ftruncateSync(fd, len) * `fd` {Integer} -* `len` {Integer} +* `len` {Integer} default = `0` Synchronous ftruncate(2). Returns `undefined`. @@ -1368,7 +1408,7 @@ added: v0.8.6 --> * `path` {String | Buffer} -* `len` {Integer} +* `len` {Integer} default = `0` * `callback` {Function} Asynchronous truncate(2). No arguments other than a possible exception are @@ -1381,9 +1421,10 @@ added: v0.8.6 --> * `path` {String | Buffer} -* `len` {Integer} +* `len` {Integer} default = `0` -Synchronous truncate(2). Returns `undefined`. +Synchronous truncate(2). Returns `undefined`. A file descriptor can also be +passed as the first argument. In this case, `fs.ftruncateSync()` is called. ## fs.unlink(path, callback)