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: #13875 Refs: #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 <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Bartosz Sosnowski <[email protected]> Reviewed-By: Roman Reiss <[email protected]> Reviewed-By: Tobias Nießen <[email protected]>
nodejs · Jul 18, 2017 · 4f0eb6f · 4f0eb6f
1 parent 32ddb66
commit 4f0eb6f
Show file tree

Hide file tree

Showing 2 changed files with 55 additions and 0 deletions.
diff --git a/doc/api/fs.md b/doc/api/fs.md
@@ -1587,6 +1587,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
@@ -2864,3 +2872,5 @@ The following constants are meant for use with the [`fs.Stats`][] object's
 [Readable Stream]: stream.html#stream_class_stream_readable
 [Writable Stream]: stream.html#stream_class_stream_writable
 [inode]: https://en.wikipedia.org/wiki/Inode
+[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
@@ -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);
+}));