doc: updated readFileSync in fs.md #12800

thelostone-mc · 2017-05-02T19:14:34Z

Refs: #10962

Updated fs.md stating fs.readFileAsync is platform specific

Documents Updated:

doc/api/fs.md

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

fhalde · 2017-05-02T19:16:38Z

prefix the PR and commit with the subsystem you changed. In this case doc
https://github.com/nodejs/node/blob/master/CONTRIBUTING.md

refack · 2017-05-02T19:24:51Z

doc/api/fs.md

@@ -1549,6 +1549,23 @@ Synchronous version of [`fs.readFile`][]. Returns the contents of the `file`.
 If the `encoding` option is specified then this function returns a
 string. Otherwise it returns a buffer.

+_Note: The behavior of `fs.readFileSync()` is platform specific. As such,
+reading a directory on macOS and Linux and Windows - see example


macOS, Linux, and Windows
We use the Oxford comma

move "see example below" to the last line of the paragraph

refack · 2017-05-02T19:27:03Z

doc/api/fs.md

@@ -1549,6 +1549,23 @@ Synchronous version of [`fs.readFile`][]. Returns the contents of the `file`.
 If the `encoding` option is specified then this function returns a
 string. Otherwise it returns a buffer.

+_Note: The behavior of `fs.readFileSync()` is platform specific. As such,
+reading a directory on macOS and Linux and Windows - see example
+below - will return an error. In contrast, on FreeBSD, contents of


remove "In contrast"

add the - "on FreeBSD, the content"

refack · 2017-05-02T19:27:39Z

doc/api/fs.md

+_Note: The behavior of `fs.readFileSync()` is platform specific. As such,
+reading a directory on macOS and Linux and Windows - see example
+below - will return an error. In contrast, on FreeBSD, contents of
+the file will be returned._


You should explain which file? as it's a directory?

@refack Would that mean :
On FreeBSD, the contents of the files in the directory will be returned.

If that is what happens, then yes, exactly.
BTW: that's strange, how do you know when one file ends and another begins... 🤔

I'm tempted to set up FreeBSD and check it out now 😛

vsemozhetbyt · 2017-05-02T19:28:47Z

Thank you!
Linter CI: https://ci.nodejs.org/job/node-test-linter/8726/

refack · 2017-05-02T19:29:58Z

Thank you very much for the contribution 🥇
(don't take the comments too hard 😉)

thelostone-mc · 2017-05-02T19:45:41Z

@refack Haha!! Well next time you won't be able to point things like this out in my next PR 😎
Thanks !!

refack · 2017-05-02T19:46:57Z

@refack Haha!! Well next time you won't be able to point things like this out in my next PR 😎
Thanks !!

I agree, the best way to learn is by doing!

thelostone-mc · 2017-05-02T19:58:21Z

@fhalde Thanks !! 🕺

mscdex · 2017-05-02T21:32:32Z

doc/api/fs.md

@@ -1549,6 +1549,23 @@ Synchronous version of [`fs.readFile`][]. Returns the contents of the `file`.
 If the `encoding` option is specified then this function returns a
 string. Otherwise it returns a buffer.

+_Note: The behavior of `fs.readFileSync()` is platform specific. As such,
+reading a directory on macOS, Linux and Windows will return an error.
+On FreeBSD, the contents of the files in directory will be returned.


What does this mean exactly? Is it just all of the files concatenated together one after the other? With or without boundaries?

I've been working (slowly) on getting as much consistency as possible in the Note sections in the docs... Can you please make this...

*Note*: The behavior...

... and do not bold the entire paragraph.

mscdex · 2017-05-02T21:32:51Z

doc/api/fs.md

+
+```js
+// macOS, Linux and Windows
+fs.readFileSync('<directory>', (err, data) => {


Synchronous methods don't accept callbacks.

mscdex · 2017-05-02T21:34:11Z

doc/api/fs.md

@@ -1549,6 +1549,23 @@ Synchronous version of [`fs.readFile`][]. Returns the contents of the `file`.
 If the `encoding` option is specified then this function returns a
 string. Otherwise it returns a buffer.

+_Note: The behavior of `fs.readFileSync()` is platform specific. As such,


I think we should be more general about what functions are affected since it would also include the async counterpart as well as anyone using fs.open('/path/to/dir') with fs.read() or their sync counterparts for example.

Won't the example clear this up? I agree your comment give room for less confusion
But the line below would clear up that confusion:

When the given path identifies a directory, the behavior of fs.readFile() and fs.readFileSync() is platform specific

Except those methods both implicitly use fs.open()/fs.read(). So really the note should be above one of those instead, but many people use readFile() as well. That is why I suggested possibly putting the note for both readFile() and fs.read() (and their sync counterparts).

jasnell · 2017-05-02T21:35:04Z

doc/api/fs.md

@@ -1549,6 +1549,23 @@ Synchronous version of [`fs.readFile`][]. Returns the contents of the `file`.
 If the `encoding` option is specified then this function returns a
 string. Otherwise it returns a buffer.

+_Note: The behavior of `fs.readFileSync()` is platform specific. As such,
+reading a directory on macOS, Linux and Windows will return an error.
+On FreeBSD, the contents of the files in directory will be returned.


I've been working (slowly) on getting as much consistency as possible in the Note sections in the docs... Can you please make this...

*Note*: The behavior...

... and do not bold the entire paragraph.

jasnell · 2017-05-02T21:37:03Z

doc/api/fs.md

@@ -1549,6 +1549,23 @@ Synchronous version of [`fs.readFile`][]. Returns the contents of the `file`.
 If the `encoding` option is specified then this function returns a
 string. Otherwise it returns a buffer.

+_Note: The behavior of `fs.readFileSync()` is platform specific. As such,


I would make this first line...

When the given path identifies a directory, the behavior of `fs.readFile()` and `fs.readFileSync()` is platform specific. On macOS, Linux and Windows, an error will be returned. On FreeBSD...

@jasnell If i were to do this, this would be first line fs.readFile().
Would we need the same to be copied even for fs.readFileSync() ?
Also , would I be giving examples for both sync and async counterparts ?

Trott · 2017-05-03T00:21:06Z

doc/api/fs.md

@@ -1377,10 +1377,10 @@ On Linux, positional writes don't work when the file is opened in append mode.
 The kernel ignores the position argument and always appends the data to
 the end of the file.

-_Note: The behavior of `fs.open()` is platform specific for some flags. As such,
+*Note*: The behavior of `fs.open()` is platform specific for some flags. As such,


Nit: platform specific -> platform-specific

(Although I know you didn't write that text. But while we're here...)

Consider it done.

Trott · 2017-05-03T00:22:26Z

doc/api/fs.md

@@ -1524,11 +1524,27 @@ If `options` is a string, then it specifies the encoding. Example:
 ```js
 fs.readFile('/etc/passwd', 'utf8', callback);
 ```
+*Note*: When the given path identifies a directory, the behavior of
+`fs.readFile()` and `fs.readFileSync()` is platform specific.On macOS, Linux


Nit: platform specific -> platform-specific

Please put a space after the period.

Comma after Linux please.

@Trott comma after Linux instead of and. Are you sure about that?

@adityaanandmc Comma after Linux and keep the and:

On macOs, Linux, and Windows, an error will be returned.

That would be a serial comma and be in accordance with the style guide for Node.js docs.

@Trott Haha yeah !! @refack had pointed that out! 😅

Trott · 2017-05-03T00:23:48Z

doc/api/fs.md

+*Note*: When the given path identifies a directory, the behavior of
+`fs.readFile()` and `fs.readFileSync()` is platform specific.On macOS, Linux
+and Windows, an error will be returned. On FreeBSD, the contents of the files
+in directory will be returned.


Is this supposed to say in the directory rather than in directory?

Trott · 2017-05-03T00:25:04Z

doc/api/fs.md

@@ -1524,11 +1524,27 @@ If `options` is a string, then it specifies the encoding. Example:
 ```js
 fs.readFile('/etc/passwd', 'utf8', callback);
 ```
+*Note*: When the given path identifies a directory, the behavior of


Would it be too imprecise to say When the path is a directory instead of When the given path identifies a directory? The former seems clearer to me, even if the latter may be more precise.

Makes sense. Will change it

Trott

I left a bunch of small comments, although most of them probably shouldn't stop this from landing if the contributor is exhausted from requests for small changes. :-D (Also, whoever lands it can probably fix any of them that are important.)

mscdex · 2017-05-03T00:31:25Z

I think a similar note should be made above fs.read()/fs.readSync() for file descriptors for directories.

thelostone-mc · 2017-05-03T06:58:15Z

@Trott Looked into the comments and changes everything accordingly except the

Comma after Linux please.

Well, any number of small fixes -> still worth it for documentation, so it's alright!

refack · 2017-05-03T11:20:52Z

doc/api/fs.md

@@ -1524,11 +1524,27 @@ If `options` is a string, then it specifies the encoding. Example:
 ```js
 fs.readFile('/etc/passwd', 'utf8', callback);
 ```
+*Note*: When the path is a directory, the behavior of
+`fs.readFile()` and [`fs.readFileSync()`][] is platform-specific. On macOS, Linux
+and Windows, an error will be returned. On FreeBSD, the contents of the files


@Trott is not just being picky. It's called the "oxford comma" and we ask for its use in our style guide

@refack
Did not see that! Got it. Fixed!
@Trott Sorry about that!! Didn't see the guide

Question: [`fs.readFileSync()`][]
Is this the right way to link this to the title fs.readFileSync() ?
Doesn't seem to be working.

Should be... It doesn't work in the GitHub web view but will work in https://nodejs.org/api/fs.html#fs_fs_readfilesync_file_options

s0m3on3 · 2017-05-04T14:04:53Z

doc/api/fs.md

+// => [Error: EISDIR: illegal operation on a directory, read <directory>]
+
+//  FreeBSD
+fs.readFileSync('<directory>'); // => null, <data>


maybe just <data> ?

s0m3on3 · 2017-05-04T14:23:08Z

doc/api/fs.md

+*Note*: When the path is a directory, the behavior of
+`fs.readFile()` and [`fs.readFileSync()`][] is platform-specific. On macOS,
+Linux, and Windows, an error will be returned. On FreeBSD, the contents
+of the files in the directory will be returned.


$ mkdir test && echo hello > test/1 && echo world > test/2 $ node -p "fs.readFileSync('test')" <Buffer 03 00 00 00> $ node -p "fs.readFileSync('/tmp')" <Buffer 03 00 00 00 00 00 00>

Doesn't look like the contents 😄
FreeBSD 11

@s0m3on3 Have look at the options parameter in the doc, you can pass the encoding format as "utf-8" to get the contents in a readable format.

If no encoding is specified, then the raw buffer is returned.

This buffer doesn't look like a readable utf8 string too

Could you try it with : node -p "fs.readFileSync('test', 'utf-8')"

I'm on MacOS, so I tried it with fs.readFileSync() on a file instead of a directory and it worked as expected!

@adityaanandmc No problem

$ node -p "fs.readFileSync('test', 'utf-8')" �

The same as

Buffer.from([3, 0, 0, 0]).toString("utf-8")

What did you expect ? 😃
Yes, macOS works as expected(throws an error), but the subject is FreeBSD, and "test" is a directory.

On FreeBSD, the contents of the files in the directory will be returned.

This is wrong.
Linux(Darwin too) doesn't allow using the read syscall to read bytes from a directory, but FreeBSD does 😐
And the result doesn't look like the contents of the files in the directory

@s0m3on3 so what are those?

$ node -p "fs.readFileSync('test')" <Buffer 03 00 00 00> $ node -p "fs.readFileSync('/tmp')" <Buffer 03 00 00 00 00 00 00>

@refack I don't know. The directory contents as a file, some internal structure

I suggest:
On FreeBSD, a representation of the directory's contents will be returned.

refack · 2017-05-05T16:35:46Z

I spun up a freeBSD vm and got this:

> fs.readFileSync('test', {encoding:'utf-8'}).replace('\u0000', ' ')
'�M\u0005 \f\u0000\u0004\u0001.\u0000\u0000\u0000\u0006�\u0004\u0000\f\u0000\u0004\u0002..\u0000\u0000�M\u0005\u0000\u001c\u0000\u0004\u0013this_is_a_directory\u0000D�\u0004\u0000\u0010\u0000\b\u0005hello\u0000��N�\u0004\u0000�\u0001\b\bduck.txt\u0000\u0001v�\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000'
> fs.readFileSync('test', {encoding:'utf-8'}).replace(/\u0000/g, ' ')
'�M\u0005 \f \u0004\u0001.   \u0006�\u0004 \f \u0004\u0002..  �M\u0005 \u001c \u0004\u0013this_is_a_directory D�\u0004 \u0010 \b\u0005hello ��N�\u0004 �\u0001\b\bduck.txt \u0001v�                                                                                                                                                                                                                                                                                                                                                                                                                                        '
> fs.readdirSync('test')
[ 'duck.txt', 'hello', 'this_is_a_directory' ]
>

So IMHO we should say:
On FreeBSD, a representation of the directory's contents will be returned.

refack · 2017-05-05T16:37:06Z

doc/api/fs.md

+*Note*: When the path is a directory, the behavior of
+`fs.readFile()` and [`fs.readFileSync()`][] is platform-specific. On macOS,
+Linux, and Windows, an error will be returned. On FreeBSD, the contents
+of the files in the directory will be returned.


I suggest:
On FreeBSD, a representation of the directory's contents will be returned.

Updated fs.md stating fs.readFileAsync is platform specific Refs: nodejs#10962

thelostone-mc · 2017-05-05T16:57:30Z

@refack Done!!

* Updated fs.md stating fs.readFileAsync is platform specific * Fix formatting of `note`s PR-URL: #12800 Refs: #10962 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

refack · 2017-05-05T17:14:49Z

Landed in: 2614d24

refack · 2017-05-05T17:36:45Z

Post land CI (Just lint): https://ci.nodejs.org/job/node-test-linter/8838/

* Updated fs.md stating fs.readFileAsync is platform specific * Fix formatting of `note`s PR-URL: nodejs#12800 Refs: nodejs#10962 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

* Updated fs.md stating fs.readFileAsync is platform specific * Fix formatting of `note`s PR-URL: #12800 Refs: #10962 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

nodejs-github-bot added doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. labels May 2, 2017

thelostone-mc mentioned this pull request May 2, 2017

Reading a directory #10962

Closed

refack suggested changes May 2, 2017

View reviewed changes

thelostone-mc force-pushed the docs branch from 503f3b6 to e5ac85c Compare May 2, 2017 19:55

thelostone-mc changed the title ~~Updated fs.md for readFileSync~~ doc: updated readFileSync in fs.md May 2, 2017

thelostone-mc force-pushed the docs branch from e5ac85c to 4b3ecf2 Compare May 2, 2017 19:57

mscdex reviewed May 2, 2017

View reviewed changes

jasnell requested changes May 2, 2017

View reviewed changes

thelostone-mc force-pushed the docs branch 2 times, most recently from e358d43 to 338bc1b Compare May 2, 2017 22:32

Trott reviewed May 3, 2017

View reviewed changes

refack approved these changes May 3, 2017

View reviewed changes

thelostone-mc force-pushed the docs branch 2 times, most recently from 4933ce0 to b4e42e0 Compare May 3, 2017 07:19

refack suggested changes May 3, 2017

View reviewed changes

thelostone-mc force-pushed the docs branch from b4e42e0 to 2776222 Compare May 3, 2017 11:58

refack approved these changes May 3, 2017

View reviewed changes

jasnell approved these changes May 4, 2017

View reviewed changes

cjihrig approved these changes May 4, 2017

View reviewed changes

refack approved these changes May 4, 2017

View reviewed changes

s0m3on3 reviewed May 4, 2017

View reviewed changes

refack suggested changes May 5, 2017

View reviewed changes

doc: updated readFileSync in fs.md

bd37c00

Updated fs.md stating fs.readFileAsync is platform specific Refs: nodejs#10962

thelostone-mc force-pushed the docs branch from e626f83 to bd37c00 Compare May 5, 2017 16:52

Merge branch 'master' into docs

a56b181

refack approved these changes May 5, 2017

View reviewed changes

refack closed this May 5, 2017

thelostone-mc deleted the docs branch May 7, 2017 05:24

jasnell mentioned this pull request May 11, 2017

8.0.0 Release Proposal #12220

Closed

gibfahn mentioned this pull request Jun 15, 2017

Auditing for 6.11.1 nodejs/Release#230

Closed

3 tasks

gibfahn added the land-on-v6.x label Jun 18, 2017

MylesBorins mentioned this pull request Jul 18, 2017

v6.11.2 proposal #14356

Merged

doc: updated readFileSync in fs.md #12800

doc: updated readFileSync in fs.md #12800

Conversation

thelostone-mc commented May 2, 2017 • edited Loading

Checklist

Affected core subsystem(s)

fhalde commented May 2, 2017

refack May 2, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thelostone-mc May 2, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt commented May 2, 2017

refack commented May 2, 2017

thelostone-mc commented May 2, 2017

refack commented May 2, 2017

thelostone-mc commented May 2, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mscdex May 2, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mscdex May 3, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thelostone-mc May 2, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Trott left a comment

Choose a reason for hiding this comment

mscdex commented May 3, 2017

thelostone-mc commented May 3, 2017

refack May 3, 2017 • edited Loading

Choose a reason for hiding this comment

thelostone-mc May 3, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

refack commented May 5, 2017

Choose a reason for hiding this comment

thelostone-mc commented May 5, 2017

refack commented May 5, 2017

refack commented May 5, 2017

thelostone-mc commented May 2, 2017 •

edited

Loading

refack May 2, 2017 •

edited

Loading

thelostone-mc May 2, 2017 •

edited

Loading

mscdex May 2, 2017 •

edited

Loading

mscdex May 3, 2017 •

edited

Loading

thelostone-mc May 2, 2017 •

edited

Loading

refack May 3, 2017 •

edited

Loading

thelostone-mc May 3, 2017 •

edited

Loading