1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: update fs read documentation for clarity

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/52453
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
This commit is contained in:
Mert Can Altin 2024-05-10 21:04:05 +03:00 committed by GitHub
parent 0e29f9bbe8
commit a27f473c26
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 31 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
doc/api/fs.md
View File

@ -3681,6 +3681,37 @@ number of bytes read is zero.
If this method is invoked as its [`util.promisify()`][]ed version, it returns
a promise for an `Object` with `bytesRead` and `buffer` properties.
The `fs.read()` method reads data from the file specified
by the file descriptor (`fd`).
The `length` argument indicates the maximum number
of bytes that Node.js
will attempt to read from the kernel.
However, the actual number of bytes read (`bytesRead`) can be lower
than the specified `length` for various reasons.
For example:
* If the file is shorter than the specified `length`, `bytesRead`
will be set to the actual number of bytes read.
* If the file encounters EOF (End of File) before the buffer could
be filled, Node.js will read all available bytes until EOF is encountered,
and the `bytesRead` parameter in the callback will indicate
the actual number of bytes read, which may be less than the specified `length`.
* If the file is on a slow network `filesystem`
or encounters any other issue during reading,
`bytesRead` can be lower than the specified `length`.
Therefore, when using `fs.read()`, it's important to
check the `bytesRead` value to
determine how many bytes were actually read from the file.
Depending on your application
logic, you may need to handle cases where `bytesRead`
is lower than the specified `length`,
such as by wrapping the read call in a loop if you require
a minimum amount of bytes.
This behavior is similar to the POSIX `preadv2` function.
### `fs.read(fd[, options], callback)`
<!-- YAML