doc: improve fs.truncate functions' documentation #7648
Conversation
thefourtheye
added
doc
thefourtheye
force-pushed
the
fs-truncate-docs
branch
2 times, most recently
from
e35369e
to
f0f04e5
Compare
| * `callback` {Function} | ||
|
|
||
| Asynchronous ftruncate(2). No arguments other than a possible exception are | ||
| given to the completion callback. | ||
|
|
||
| If the file referred by the file descriptor has more number of bytes than the | ||
| `len` then, only the first `len` bytes will be retained in the file. |
There was a problem hiding this comment.
From ftruncate(2):
The
truncate()andftruncate()functions cause the regular file named bypathor referenced byfdto be truncated to a size of preciselylengthbytes.If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is extended, and the extended part reads as null bytes (
'\0').
I think something along these lines might be nice?
There was a problem hiding this comment.
I don't know how to write this better. Suggestions?
There was a problem hiding this comment.
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.
How about that (it’s only a minor difference to what you wrote)?
The second paragraph below could probably be written quite closely to the man page, e.g.
If the file previously was shorter than `len` bytes, it is extended, and the extended part reads as null bytes ('\0').
|
LGTM with a couple of nits. |
|
@thefourtheye feel free to do with my suggestion whatever you prefer, this LGTM either way! |
thefourtheye
force-pushed
the
fs-truncate-docs
branch
from
6d3375c
to
a005cc0
Compare
If the file is over truncated, then the rest of the file should be filled with zeroes. These tests ensure the same.
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.
thefourtheye
force-pushed
the
fs-truncate-docs
branch
from
a005cc0
to
7c20ba9
Compare
| For example, the following program retains only the first four bytes of the file | ||
|
|
||
| ```js | ||
| console.log(fs.readFileSync('temp.txt', 'utf8'); |
|
Left a few comments, this still LGTM! :) |
|
Thanks for pointing them out @addaleax. I fixed them, except the over-truncation (couldn't think of anything better :() |
|
Thanks! As far as I am concerned this seems good to go. |
|
I don’t expect any surprises, but new CI because the last one is a 404 by now: https://ci.nodejs.org/job/node-test-commit/4795/ |
|
LGTM! |
If the file is over truncated, then the rest of the file should be filled with null bytes. These tests ensure the same. PR-URL: #7648 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com>
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>
If the file is over truncated, then the rest of the file should be filled with null bytes. These tests ensure the same. PR-URL: nodejs#7648 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com>
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: nodejs#7648 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com>
If the file is over truncated, then the rest of the file should be filled with null bytes. These tests ensure the same. PR-URL: #7648 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com>
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>
|
this is not landing cleanly on v4.x. Please feel free to manually backport |
Checklist
Affected core subsystem(s)
doc, fs
Description of change
The default value of the
lenparameter is zero and it is included inthe documentation.
This patch also has an example of how
ftruncatecan be used.@nodejs/fs @nodejs/documentation