fs: Buffer and encoding enhancements to fs API

This makes several changes:

1. Allow path/filename to be passed in as a Buffer on fs methods
2. Add `options.encoding` to fs.readdir, fs.readdirSync, fs.readlink,
   fs.readlinkSync and fs.watch.
3. Documentation updates

For 1... it's now possible to do:

```js
fs.open(Buffer('/fs/foo/bar'), 'w+', (err, fd) => { });
```

For 2...
```js
fs.readdir('/fs/foo/bar', {encoding:'hex'}, (err,list) => { });

fs.readdir('/fs/foo/bar', {encoding:'buffer'}, (err, list) => { });
```

encoding can also be passed as a string

```js
fs.readdir('/fs/foo/bar', 'hex', (err,list) => { });
```

The default encoding is set to UTF8 so this addresses the
discrepency that existed previously between fs.readdir and
fs.watch handling filenames differently.

Fixes: https://github.com/nodejs/node/issues/2088
Refs: https://github.com/nodejs/node/issues/3519
PR-URL: https://github.com/nodejs/node/pull/5616
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Trevor Norris <trev.norris@gmail.com>

1 files changed, 41 insertions, 0 deletions

diff --git a/test/parallel/test-fs-buffer.js b/test/parallel/test-fs-buffer.js
new file mode 100644
index 0000000000..6f142310f5
--- /dev/null
+++ b/test/parallel/test-fs-buffer.js
@@ -0,0 +1,41 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+common.refreshTmpDir();
+
+assert.doesNotThrow(() => {
+  fs.access(Buffer.from(common.tmpDir), common.mustCall((err) => {
+    if (err) throw err;
+  }));
+});
+
+assert.doesNotThrow(() => {
+  const buf = Buffer.from(path.join(common.tmpDir, 'a.txt'));
+  fs.open(buf, 'w+', common.mustCall((err, fd) => {
+    if (err) throw err;
+    assert(fd);
+    fs.close(fd, common.mustCall(() => {
+      fs.unlinkSync(buf);
+    }));
+  }));
+});
+
+assert.throws(() => {
+  fs.accessSync(true);
+}, /path must be a string or Buffer/);
+
+const dir = Buffer.from(common.fixturesDir);
+fs.readdir(dir, 'hex', common.mustCall((err, list) => {
+  if (err) throw err;
+  list = list.map((i) => {
+    return Buffer.from(i, 'hex').toString();
+  });
+  fs.readdir(dir, common.mustCall((err, list2) => {
+    if (err) throw err;
+    assert.deepStrictEqual(list, list2);
+  }));
+}));