What does `fs.read`'s `length` argument indicate?

[lucacasonato]

Affected URL(s)

https://nodejs.org/api/fs.html#fsreadfd-buffer-offset-length-position-callback

Description of the problem

It is not clear from Node's fs.read() docs, whether the length argument indicates the maximum number of bytes that Node will attempt to read from the kernel, or whether Node will return exactly length bytes (possibly making multiple read syscalls in the process).

Ie: if I call fs.read() with length = 10, which of these holds:

1. When reading a file that is 9 bytes long, exactly 9 bytes are read and bytesRead is set to 9.
2. When reading a file that is 9 bytes long, the callback is called with an error because EOF was encountered before the buffer could be filled.
3. When reading a file that is 11 bytes long, exactly 10 bytes are read and bytesRead is set to 10.
4. When reading a file that is 11 bytes long, but the file is on a slow network filesystem that only reads in chunks of 5 bytes per second, 5 bytes are read and bytesRead is set to 5.

This is an important thing to document because it determines whether you need to wrap the read call in a loop (like the Linux syscall) if you need a minimum amount of bytes, or whether you do not have to do this.

[targos]

@nodejs/fs

[mcollina]

1. no. bytesRead can be lower for any sort of reason.
2. no
3. no, bytesRead can be lower
4. yes

This is an important thing to document because it determines whether you need to wrap the read call in a loop (like the Linux syscall) if you need a minimum amount of bytes, or whether you do not have to do this.

Yes, you need to loop.
It's equivalent of preadv2 https://man7.org/linux/man-pages/man2/preadv.2.html.

[lucacasonato]

Great - thank you, this matches my expectation. Do you want to keep this issue open to track updates of the docs or shall I close it?

[joyeecheung]

I think we should keep it open so that someone improves the doc to avoid confusing future readers.

[jsonOdison]

is it still open , can i still contribute ?
@joyeecheung

[LiviaMedeiros]

#52453 was merged, so I guess this can be closed.