Skip to content

Commit ab76d28

Browse files
author
Mert Can Altin
committed
doc update fs.read() documentation for clarity
1 parent df9cb97 commit ab76d28

File tree

1 file changed

+12
-0
lines changed

1 file changed

+12
-0
lines changed

doc/api/fs.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3072,6 +3072,18 @@ extended part is filled with null bytes (`'\0'`):
30723072
30733073
If `len` is negative then `0` will be used.
30743074
3075+
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.
3076+
3077+
For example:
3078+
- If the file is shorter than the specified `length`, `bytesRead` will be set to the actual number of bytes read.
3079+
- If the file encounters EOF (End of File) before the buffer could be filled, the callback will be called with an error.
3080+
- If the file is longer than the specified `length`, only `length` bytes will be read from the file, and `bytesRead` will be set to `length`.
3081+
- If the file is on a slow network filesystem or encounters any other issue during reading, `bytesRead` can be lower than the specified `length`.
3082+
3083+
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.
3084+
3085+
This behavior is similar to the POSIX `preadv2` function.
3086+
30753087
### `fs.futimes(fd, atime, mtime, callback)`
30763088
30773089
<!-- YAML

0 commit comments

Comments
 (0)