doc,test: fs - reserved characters under win32

Explain the behavior of `fs.open()` under win32 that file path contains
some characters and add some test cases for them.

< (less than)
> (greater than)
: (colon)
" (double quote)
/ (forward slash)
\ (backslash)
| (vertical bar or pipe)
? (question mark)
* (asterisk)

PR-URL: https://github.com/nodejs/node/pull/13875
Refs: https://github.com/nodejs/node/issues/13868
Refs: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx
Refs: https://msdn.microsoft.com/en-us/library/windows/desktop/bb540537.aspx
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Bartosz Sosnowski <bartosz@janeasystems.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>

2 files changed, 55 insertions, 0 deletions

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 73dcf213e3..3b7cdf33d7 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -1268,6 +1268,14 @@ fs.open('<directory>', 'a+', (err, fd) => {
 });
 ```
 
+Some characters (`< > : " / \ | ? *`) are reserved under Windows as documented
+by [Naming Files, Paths, and Namespaces][]. Under NTFS, if the filename contains
+a colon, Node.js will open a file system stream, as described by
+[this MSDN page][MSDN-Using-Streams].
+
+Functions based on `fs.open()` exhibit this behavior as well. eg.
+`fs.writeFile()`, `fs.readFile()`, etc.
+
 ## fs.openSync(path, flags[, mode])
 <!-- YAML
 added: v0.1.21
@@ -2264,3 +2272,5 @@ The following constants are meant for use with the [`fs.Stats`][] object's
 [`ReadDirectoryChangesW`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365465%28v=vs.85%29.aspx
 [`AHAFS`]: https://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/
 [Common System Errors]: errors.html#errors_common_system_errors
+[Naming Files, Paths, and Namespaces]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx
+[MSDN-Using-Streams]: https://msdn.microsoft.com/en-us/library/windows/desktop/bb540537.aspx
diff --git a/test/parallel/test-fs-write-file-invalid-path.js b/test/parallel/test-fs-write-file-invalid-path.js
new file mode 100644
index 0000000000..c45eaccf2b
--- /dev/null
+++ b/test/parallel/test-fs-write-file-invalid-path.js
@@ -0,0 +1,45 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+if (!common.isWindows)
+  common.skip('This test is for Windows only.');
+
+common.refreshTmpDir();
+
+const DATA_VALUE = 'hello';
+
+// Refs: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx
+// Ignore '/', '\\' and ':'
+const RESERVED_CHARACTERS = '<>"|?*';
+
+[...RESERVED_CHARACTERS].forEach((ch) => {
+  const pathname = path.join(common.tmpDir, `somefile_${ch}`);
+  assert.throws(
+    () => {
+      fs.writeFileSync(pathname, DATA_VALUE);
+    },
+    /^Error: ENOENT: no such file or directory, open '.*'$/,
+    `failed with '${ch}'`);
+});
+
+// Test for ':' (NTFS data streams).
+// Refs: https://msdn.microsoft.com/en-us/library/windows/desktop/bb540537.aspx
+const pathname = path.join(common.tmpDir, 'foo:bar');
+fs.writeFileSync(pathname, DATA_VALUE);
+
+let content = '';
+const fileDataStream = fs.createReadStream(pathname, {
+  encoding: 'utf8'
+});
+
+fileDataStream.on('data', (data) => {
+  content += data;
+});
+
+fileDataStream.on('end', common.mustCall(() => {
+  assert.strictEqual(content, DATA_VALUE);
+}));