Permalink
Browse files

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.

PR-URL: #7648
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
  • Loading branch information...
thefourtheye committed Aug 27, 2016
1 parent 82c7a9c commit c8619ea3c38d025e6558ee19b40cd5b8f9d49f73
Showing with 47 additions and 5 deletions.
  1. +47 −5 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

0 comments on commit c8619ea

Please sign in to comment.