createReadStream
Unlike the 16 KiB default highWaterMark
for a stream.Readable
, the stream returned by this method has a default highWaterMark
of 64 KiB.
options
can include start
and end
values to read a range of bytes from the file instead of the entire file. Both start
and end
are inclusive and start counting at 0, allowed values are in the \[0, Number.MAX_SAFE_INTEGER
\] range. If start
is omitted or undefined
, filehandle.createReadStream()
reads sequentially from the current file position. The encoding
can be any one of those accepted by Buffer
.
If the FileHandle
points to a character device that only supports blocking reads (such as keyboard or sound card), read operations do not finish until data is available. This can prevent the process from exiting and the stream from closing naturally.
By default, the stream will emit a 'close'
event after it has been destroyed. Set the emitClose
option to false
to change this behavior.
import { open } from 'node:fs/promises';
const fd = await open('/dev/input/event0');
// Create a stream from some character device.
const stream = fd.createReadStream();
setTimeout(() => {
stream.close(); // This may not close the stream.
// Artificially marking end-of-stream, as if the underlying resource had
// indicated end-of-file by itself, allows the stream to close.
// This does not cancel pending read operations, and if there is such an
// operation, the process may still not be able to exit successfully
// until it finishes.
stream.push(null);
stream.read(0);
}, 100);
If autoClose
is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak. If autoClose
is set to true (default behavior), on 'error'
or 'end'
the file descriptor will be closed automatically.
An example to read the last 10 bytes of a file which is 100 bytes long:
import { open } from 'node:fs/promises';
const fd = await open('sample.txt');
fd.createReadStream({ start: 90, end: 99 });
Since
v16.11.0