@@ -3681,6 +3681,37 @@ number of bytes read is zero. |
3681 | 3681 | If this method is invoked as its [`util.promisify()`][]ed version, it returns |
3682 | 3682 | a promise for an `Object` with `bytesRead` and `buffer` properties. |
3683 | 3683 |
|
| 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 | +
|
3684 | 3715 | ### `fs.read(fd[, options], callback)` |
3685 | 3716 |
|
3686 | 3717 | <!-- YAML |
|