Skip to content

Commit 5dab187

Browse files
mertcanaltintargos
authored andcommitted
doc: update fs read documentation for clarity
PR-URL: #52453 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Marco Ippolito <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent 7ca83a5 commit 5dab187

File tree

1 file changed

+31
-0
lines changed

1 file changed

+31
-0
lines changed

doc/api/fs.md

+31
Original file line numberDiff line numberDiff line change
@@ -3681,6 +3681,37 @@ number of bytes read is zero.
36813681
If this method is invoked as its [`util.promisify()`][]ed version, it returns
36823682
a promise for an `Object` with `bytesRead` and `buffer` properties.
36833683
3684+
The `fs.read()` method reads data from the file specified
3685+
by the file descriptor (`fd`).
3686+
The `length` argument indicates the maximum number
3687+
of bytes that Node.js
3688+
will attempt to read from the kernel.
3689+
However, the actual number of bytes read (`bytesRead`) can be lower
3690+
than the specified `length` for various reasons.
3691+
3692+
For example:
3693+
3694+
* If the file is shorter than the specified `length`, `bytesRead`
3695+
will be set to the actual number of bytes read.
3696+
* If the file encounters EOF (End of File) before the buffer could
3697+
be filled, Node.js will read all available bytes until EOF is encountered,
3698+
and the `bytesRead` parameter in the callback will indicate
3699+
the actual number of bytes read, which may be less than the specified `length`.
3700+
* If the file is on a slow network `filesystem`
3701+
or encounters any other issue during reading,
3702+
`bytesRead` can be lower than the specified `length`.
3703+
3704+
Therefore, when using `fs.read()`, it's important to
3705+
check the `bytesRead` value to
3706+
determine how many bytes were actually read from the file.
3707+
Depending on your application
3708+
logic, you may need to handle cases where `bytesRead`
3709+
is lower than the specified `length`,
3710+
such as by wrapping the read call in a loop if you require
3711+
a minimum amount of bytes.
3712+
3713+
This behavior is similar to the POSIX `preadv2` function.
3714+
36843715
### `fs.read(fd[, options], callback)`
36853716
36863717
<!-- YAML

0 commit comments

Comments
 (0)