Skip to content

Commit

Permalink
doc,test: fs - reserved characters under win32
Browse files Browse the repository at this point in the history
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]>
  • Loading branch information
XadillaX authored and addaleax committed Jul 18, 2017
1 parent 32ddb66 commit 4f0eb6f
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 0 deletions.
10 changes: 10 additions & 0 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
45 changes: 45 additions & 0 deletions test/parallel/test-fs-write-file-invalid-path.js
Original file line number Diff line number Diff line change
@@ -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);
}));

0 comments on commit 4f0eb6f

Please sign in to comment.