From ccd3d9fe6792d828ccb1fd2f0de28b5890409d84 Mon Sep 17 00:00:00 2001 From: Nikolai Vavilov Date: Sat, 2 Apr 2016 16:44:18 +0300 Subject: [PATCH 1/2] fs: document intention and dangers of Buffer API --- doc/api/fs.markdown | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 6fdea6f7f0edf4..872f5c984a5021 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -94,6 +94,17 @@ Error: EISDIR, read ``` +## Buffer API + +`fs` functions support passing and receiving paths as both strings and Buffers. +The latter is intended for filesystems which support non-UTF-8 filenames (except +NTFS, where the conversion to UTF-8 is done automatically) and is normally not +needed. + +**Caution:** the Buffer API is not portable. On NTFS and HFS+, the incoming +Buffers are always encoded in UTF-8, and passing non-UTF-8 encoded Buffers to +`fs` functions won't work as expected. + ## Class: fs.FSWatcher Objects returned from `fs.watch()` are of this type. From 26ee7d8032fa8a6613f5fc12e64a020f34446548 Mon Sep 17 00:00:00 2001 From: Nikolai Vavilov Date: Tue, 12 Apr 2016 13:51:01 +0300 Subject: [PATCH 2/2] Update fs.markdown --- doc/api/fs.markdown | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 872f5c984a5021..70e7a34d1443a1 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -96,14 +96,15 @@ Error: EISDIR, read ## Buffer API -`fs` functions support passing and receiving paths as both strings and Buffers. -The latter is intended for filesystems which support non-UTF-8 filenames (except -NTFS, where the conversion to UTF-8 is done automatically) and is normally not -needed. - -**Caution:** the Buffer API is not portable. On NTFS and HFS+, the incoming -Buffers are always encoded in UTF-8, and passing non-UTF-8 encoded Buffers to -`fs` functions won't work as expected. +`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, as the string +API converts to and from UTF-8 automatically. + +*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. ## Class: fs.FSWatcher