From 8760dc60243c50665aa0442e2e4ff7d1c1a113f5 Mon Sep 17 00:00:00 2001 From: Nikolai Vavilov Date: Sat, 2 Apr 2016 16:44:18 +0300 Subject: [PATCH] doc: document intention and dangers of fs module Buffer API PR-URL: https://github.com/nodejs/node/pull/6020 Reviewed-By: James M Snell --- doc/api/fs.markdown | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 91f6731791258f..0c427ef1319ea3 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -94,6 +94,18 @@ Error: EISDIR, read ``` +## Buffer API + +`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 Objects returned from `fs.watch()` are of this type.