doc: clarify create{Read,Write}Stream fd option

benjamincburns · chrisdickinson · commit 5b9e5bdd03ef · 2014-12-15T22:25:58.000-08:00
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: nodejs/node-v0.x-archive#7707 Fixes: nodejs/node-v0.x-archive#7707 Fixes: nodejs/node-v0.x-archive#7708 Fixes: nodejs/node-v0.x-archive#4367 Reviewed-By: Chris Dickinson <christopher.s.dickinson@gmail.com>
diff --git 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,13 +778,19 @@ 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
 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).
