Documentation: `fd` option of `fs.createReadStream`

[natevw]

The documentation for fs.createReadStream shows that the default value of an fd option is null, but it does not explain what it is for or how it interacts with the path parameter (and mode/flags options, etc.) and the autoClose option.

I did find this brief discussion:
https://groups.google.com/forum/#!topic/nodejs/IhLJr57EDWc

[natevw]

Here's some items of interest when passing an fd to fs.createWriteStream:

• the 'open' event is not fired if you pass in a file descriptor
• if you don't pass in a file descriptor, it won't be set on your passed-in options object. I.e. 'fd' will not get magically/oddly filled in with a fd and therefore setting autoClose:false without also providing fd would not be a bad idea. (It will be at stream.fd but that is not publicly documented)the stream's 'open' event is documented to expose the fd
• …TBD…

DISCLAIMER — please don't take the above "documentation" as an official API commitment, I am just some yokel nosing around in someone's else's code to see how it might currently behave.

[benjamincburns]

You probably don't want lots of +1 and "me too" comments, but the lack of documentation here did waste a good day or so of my time. I'm writing a TUN/TAP device module in mostly pure JavaScript (using ioctl and ref-struct). Ideally once the TUN/TAP device is open I'd like to pass it back to the module consumer as a Duplex stream.

I've written this up as a StackOverflow question. Someone commented that this functionality exists, but being that it's not documented I don't know whether or not it's part of the public API and whether or not it can be used without fear of it disappearing on me without warning.

As an aside, I'd really love it if it were possible to do new stream.Duplex({fd: myFD }) and it "just worked." I know this has been debated in other forms elsewhere, but there are a myriad of "long tail" use cases which would benefit from this.

[benjamincburns]

Of course, if someone was willing to provide me with the highlights, I'd be very happy to submit a pull request. Feel free to get in touch with me via skype at 'benjamin.burns' if that's easier than commenting here.

[indutny]

Could you please submit a PR fixing it?

[natevw]

Sounds like it's not left undocumented on purpose, then, and the maintainers are tentatively okay with committing to the current /de facto/ behavior?

[natevw]

@benjamincburns assuming the current fd option to fs.createReadStream/fs.createWriteStream becomes /de jure/ interface, you might want to just wrap those up in a little npm module that creates a duplex stream as you describe!

[benjamincburns]

@natevw -- Would also be nice if there was a fs.createDuplexStream

@indutny - Will do on the documentation, provided that everyone is satisfied that the functionality isn't going to disappear. Can you confirm? Also, would you accept a separate PR for fs.createDuplexStream?

[indutny]

@benjamincburns go ahead and open it! :)

[chrisdickinson]

Addressed by #8001.