From 5b9e5bdd03ef5c53f370e414c5a964fccb4ac030 Mon Sep 17 00:00:00 2001 From: Ben Burns Date: Sun, 27 Jul 2014 02:04:46 +1200 Subject: [PATCH] doc: clarify create{Read,Write}Stream fd option Clarify the fd option: it is preferred to the path parameter, omits the "open" event if given, and is available on WriteStreams as well. PR-URL: https://github.com/joyent/node/issues/7707 Fixes: https://github.com/joyent/node/issues/7707 Fixes: https://github.com/joyent/node/issues/7708 Fixes: https://github.com/joyent/node/issues/4367 Reviewed-By: Chris Dickinson --- doc/api/fs.markdown | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index c6bfa2456bc..124962c2a11 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -745,6 +745,9 @@ Returns a new ReadStream object (See `Readable Stream`). the file instead of the entire file. Both `start` and `end` are inclusive and start at 0. The `encoding` can be `'utf8'`, `'ascii'`, or `'base64'`. +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. + 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 there's no file descriptor leak. If `autoClose` is set to true (default @@ -775,6 +778,7 @@ Returns a new WriteStream object (See `Writable Stream`). { flags: 'w', encoding: null, + fd: null, mode: 0666 } `options` may also include a `start` option to allow writing data at @@ -782,6 +786,11 @@ some position past the beginning of the file. Modifying a file rather than replacing it may require a `flags` mode of `r+` rather than the default mode `w`. +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. + + ## Class: fs.WriteStream `WriteStream` is a [Writable Stream](stream.html#stream_class_stream_writable).