From f4ca007b42ff4c96ff4adf5f110af81888156a19 Mon Sep 17 00:00:00 2001 From: Carl Lei Date: Tue, 3 Nov 2015 19:21:31 +0800 Subject: [PATCH] doc: clarify that fs streams expect blocking fd This clarifies that fs.createReadStream and fs.createWriteStream, when passed a fd, expects the fd to be blocking, and suggests net.Socket as an alternative. PR-URL: https://github.com/nodejs/node/pull/3641 Reviewed-By: Ben Noordhuis Reviewed-By: James M Snell --- doc/api/fs.markdown | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 86e77539b922fa..6511b274c3c841 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -307,6 +307,8 @@ start at 0. The `encoding` can be any one of those accepted by [Buffer][]. If `fd` is specified, `ReadStream` will ignore the `path` argument and will use the specified file descriptor. This means that no `open` event will be emitted. +Note that `fd` should be blocking; non-blocking `fd`s should be passed to +`net.Socket`. If `autoClose` is false, then the file descriptor won't be closed, even if there's an error. It is your responsibility to close it and make sure @@ -341,7 +343,8 @@ default mode `w`. The `defaultEncoding` can be any one of those accepted by [Buf Like `ReadStream` above, if `fd` is specified, `WriteStream` will ignore the `path` argument and will use the specified file descriptor. This means that no -`open` event will be emitted. +`open` event will be emitted. Note that `fd` should be blocking; non-blocking +`fd`s should be passed to `net.Socket`. If `options` is a string, then it specifies the encoding.