fs: document intention and caveats of Buffer API

[seishun]

Pull Request check-list

Please make sure to review and check all of these items:

• Is the commit message formatted according to [CONTRIBUTING.md][0]?

Affected core subsystem(s)

fs

Description of change

This should prevent potential confusion of newcomers.

[jasnell]

Perhaps,

`fs` functions support passing and receiving paths as both strings
and Buffers. The latter is intended to make it easier to work with
filesystems that allow for non-UTF-8 filenames. For most typical
uses, working with paths as Buffers will be unnecessary.

*Note* that on certain file systems (such as NTFS and HFS+) Node.js
will always encode filenames as UTF-8. On such file systems, passing 
non-UTF-8 encoded Buffers to `fs` functions will not work as expected.

[jasnell]

Good idea generally LGTM but offered some rewording.

[seishun]

The latter is intended to make it easier to work with filesystems that allow for non-UTF-8 filenames.

Actually it's impossible to work with non-UTF-8 filenames using the string API, so this is a bit misleading.

on certain file systems (such as NTFS and HFS+) Node.js will always encode filenames as UTF-8.

Somewhat misleading too. This is only true on NTFS. On NFS+, Node.js doesn't touch filenames - UTF-8 is enforced by the file system.

[jasnell]

`fs` functions support passing and receiving paths as both strings
and Buffers. The latter is intended to make it possible to work with
filesystems that allow for non-UTF-8 filenames. For most typical
uses, working with paths as Buffers will be unnecessary.

*Note* that on certain file systems (such as NTFS and HFS+) filenames
will always be encoded as UTF-8. On such file systems, passing 
non-UTF-8 encoded Buffers to `fs` functions will not work as expected.

[addaleax]

As this explicitly targets newcomers – it might be a good idea to mention that NTFS and HFS+ are the Windows and OS X standard file systems, respectively, if that’s not too distracting from the point?

[seishun]

@jasnell Updated using your suggestions, plus an addition from me. I thought we should make it clear somewhere that the string API is just Buffer API with automatic conversion to and from UTF-8.

[jasnell]

LGTM

[jasnell]

Landed in cf29b2f

[MylesBorins]

@jasnell is this relevant to lts?

[jasnell]

No. This is specific to the new buffer support in the fs module. Not
applicable to lts
On Apr 20, 2016 11:49 PM, "Myles Borins" notifications@github.com wrote:

@jasnell https://github.com/jasnell is this relevant to lts?

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#6020 (comment)