doc: improve fs.truncate functions' documentation

doc/api/fs.md

@@ -739,19 +739,60 @@ 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
+console.log(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 <Buffer 4e 6f 64 65 2e 6a 73 00 00 00>
+  // ('Node.js\0\0\0' in UTF8)
+```
+
+The last three bytes are null bytes ('\0'), to compensate the over-truncation.
+
 ## fs.ftruncateSync(fd, len)
 <!-- YAML
 added: v0.8.6
 -->
 
 * `fd` {Integer}
-* `len` {Integer}
+* `len` {Integer} default = `0`
 
 Synchronous ftruncate(2). Returns `undefined`.
 
@@ -1368,7 +1409,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 +1422,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)
 <!-- YAML

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')));
+  }));
+}