1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: remove "note that" from fs doc

Browse Source 
Remove "note that" from the fs documentation, along with other minor
nearby improvements.

Before:

    Note that some characters are obscured by Strong Bad's head.

After:

    Some characters are obscured by Strong Bad's head.

PR-URL: https://github.com/nodejs/node/pull/21646
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
This commit is contained in:
Rich Trott 2018-07-03 16:51:28 -07:00
parent e55bdde925
commit f545ae9589
1 changed files with 56 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
doc/api/fs.md
View File

@ -45,9 +45,9 @@ try {
}
```
Note that there is no guaranteed ordering when using asynchronous methods.
So the following is prone to error because the `fs.stat()` operation may
complete before the `fs.rename()` operation.
There is no guaranteed ordering when using asynchronous methods. So the
following is prone to error because the `fs.stat()` operation may complete
before the `fs.rename()` operation:
```js
fs.rename('/tmp/hello', '/tmp/world', (err) => {
@ -150,8 +150,8 @@ fs.open(Buffer.from('/open/some/file.txt'), 'r', (err, fd) => {
});
```
*Note:* On Windows Node.js follows the concept of per-drive working directory.
This behavior can be observed when using a drive path without a backslash. For
On Windows, Node.js follows the concept of per-drive working directory. This
behavior can be observed when using a drive path without a backslash. For
example `fs.readdirSync('c:\\')` can potentially return a different result than
`fs.readdirSync('c:')`. For more information, see
[this MSDN page][MSDN-Rel-Path].
@ -278,9 +278,9 @@ eventually cause an application to crash.
## Threadpool Usage
Note that all file system APIs except `fs.FSWatcher()` and those that are
explicitly synchronous use libuv's threadpool, which can have surprising and
negative performance implications for some applications, see the
All file system APIs except `fs.FSWatcher()` and those that are explicitly
synchronous use libuv's threadpool, which can have surprising and negative
performance implications for some applications. See the
[`UV_THREADPOOL_SIZE`][] documentation for more information.
## Class: fs.FSWatcher
@ -689,15 +689,13 @@ The times in the stat object have the following semantics:
* `birthtime` "Birth Time" - Time of file creation. Set once when the
file is created. On filesystems where birthtime is not available,
this field may instead hold either the `ctime` or
`1970-01-01T00:00Z` (ie, unix epoch timestamp `0`). Note that this
value may be greater than `atime` or `mtime` in this case. On Darwin
and other FreeBSD variants, also set if the `atime` is explicitly
set to an earlier value than the current `birthtime` using the
utimes(2) system call.
`1970-01-01T00:00Z` (ie, unix epoch timestamp `0`). This value may be greater
than `atime` or `mtime` in this case. On Darwin and other FreeBSD variants,
also set if the `atime` is explicitly set to an earlier value than the current
`birthtime` using the utimes(2) system call.
Prior to Node.js v0.12, the `ctime` held the `birthtime` on Windows
systems. Note that as of v0.12, `ctime` is not "creation time", and
on Unix systems, it never was.
Prior to Node.js 0.12, the `ctime` held the `birthtime` on Windows systems. As
of 0.12, `ctime` is not "creation time", and on Unix systems, it never was.
## Class: fs.WriteStream
<!-- YAML
@ -1117,11 +1115,10 @@ For example, the octal value `0o765` means:
* The group may read and write the file.
* Others may read and execute the file.
Note: When using raw numbers where file modes are expected,
any value larger than `0o777` may result in platform-specific
behaviors that are not supported to work consistently.
Therefore constants like `S_ISVTX`, `S_ISGID` or `S_ISUID` are
not exposed in `fs.constants`.
When using raw numbers where file modes are expected, any value larger than
`0o777` may result in platform-specific behaviors that are not supported to work
consistently. Therefore constants like `S_ISVTX`, `S_ISGID` or `S_ISUID` are not
exposed in `fs.constants`.
Caveats: on Windows only the write permission can be changed, and the
distinction among the permissions of group, owner or others is not
@ -1378,8 +1375,8 @@ The `encoding` can be any one of those accepted by [`Buffer`][].
If `fd` is specified, `ReadStream` will ignore the `path` argument and will use
the specified file descriptor. This means that no `'open'` event will be
emitted. Note that `fd` should be blocking; non-blocking `fd`s should be passed
to [`net.Socket`][].
emitted. `fd` should be blocking; non-blocking `fd`s should be passed to
[`net.Socket`][].
If `autoClose` is false, then the file descriptor won't be closed, even if
there's an error. It is the application's responsibility to close it and make
@ -1442,8 +1439,8 @@ file descriptor leak.
Like [`ReadStream`][], if `fd` is specified, [`WriteStream`][] will ignore the
`path` argument and will use the specified file descriptor. This means that no
`'open'` event will be emitted. Note that `fd` should be blocking; non-blocking
`fd`s should be passed to [`net.Socket`][].
`'open'` event will be emitted. `fd` should be blocking; non-blocking `fd`s
should be passed to [`net.Socket`][].
If `options` is a string, then it specifies the encoding.
@ -1473,11 +1470,11 @@ fs.exists('/etc/passwd', (exists) => {
});
```
**Note that the parameter to this callback is not consistent with other
Node.js callbacks.** Normally, the first parameter to a Node.js callback is
an `err` parameter, optionally followed by other parameters. The
`fs.exists()` callback has only one boolean parameter. This is one reason
`fs.access()` is recommended instead of `fs.exists()`.
**The parameters for this callback are not consistent with other Node.js
callbacks.** Normally, the first parameter to a Node.js callback is an `err`
parameter, optionally followed by other parameters. The `fs.exists()` callback
has only one boolean parameter. This is one reason `fs.access()` is recommended
instead of `fs.exists()`.
Using `fs.exists()` to check for the existence of a file before calling
`fs.open()`, `fs.readFile()` or `fs.writeFile()` is not recommended. Doing
@ -1573,10 +1570,9 @@ changes:
Synchronous version of [`fs.exists()`][].
Returns `true` if the path exists, `false` otherwise.
Note that `fs.exists()` is deprecated, but `fs.existsSync()` is not.
(The `callback` parameter to `fs.exists()` accepts parameters that are
inconsistent with other Node.js callbacks. `fs.existsSync()` does not use
a callback.)
`fs.exists()` is deprecated, but `fs.existsSync()` is not. The `callback`
parameter to `fs.exists()` accepts parameters that are inconsistent with other
Node.js callbacks. `fs.existsSync()` does not use a callback.
## fs.fchmod(fd, mode, callback)
<!-- YAML
@ -2149,9 +2145,8 @@ fs.mkdtemp(tmpDir, (err, folder) => {
if (err) throw err;
console.log(folder);
// Will print something similar to `/tmpabc123`.
// Note that a new temporary directory is created
// at the file system root rather than *within*
// the /tmp directory.
// A new temporary directory is created at the file system root
// rather than *within* the /tmp directory.
});
// This method is *CORRECT*:
@ -2204,8 +2199,8 @@ changes:
Asynchronous file open. See open(2).
`mode` sets the file mode (permission and sticky bits), but only if the file was
created. Note that on Windows only the write permission can be manipulated,
see [`fs.chmod()`][].
created. On Windows, only the write permission can be manipulated; see
[`fs.chmod()`][].
The callback gets two arguments `(err, fd)`.
@ -2843,9 +2838,9 @@ changes:
Asynchronous symlink(2). No arguments other than a possible exception are given
to the completion callback. The `type` argument can be set to `'dir'`,
`'file'`, or `'junction'` and is only available on
Windows (ignored on other platforms). Note that Windows junction points require
the destination path to be absolute. When using `'junction'`, the `target`
argument will automatically be normalized to absolute path.
Windows (ignored on other platforms). Windows junction points require the
destination path to be absolute. When using `'junction'`, the `target` argument
will automatically be normalized to absolute path.
Here is an example below:
@ -3086,10 +3081,10 @@ The listener callback gets two arguments `(eventType, filename)`. `eventType`
is either `'rename'` or `'change'`, and `filename` is the name of the file
which triggered the event.
Note that on most platforms, `'rename'` is emitted whenever a filename appears
or disappears in the directory.
On most platforms, `'rename'` is emitted whenever a filename appears or
disappears in the directory.
Also note the listener callback is attached to the `'change'` event fired by
The listener callback is attached to the `'change'` event fired by
[`fs.FSWatcher`][], but it is not the same thing as the `'change'` value of
`eventType`.
@ -3266,9 +3261,8 @@ The callback will be given three arguments `(err, bytesWritten, buffer)` where
If this method is invoked as its [`util.promisify()`][]ed version, it returns
a `Promise` for an `Object` with `bytesWritten` and `buffer` properties.
Note that it is unsafe to use `fs.write` multiple times on the same file
without waiting for the callback. For this scenario,
`fs.createWriteStream` is strongly recommended.
It is unsafe to use `fs.write()` multiple times on the same file without waiting
for the callback. For this scenario, `fs.createWriteStream()` is recommended.
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
@ -3310,12 +3304,12 @@ the current position. See pwrite(2).
`encoding` is the expected string encoding.
The callback will receive the arguments `(err, written, string)` where `written`
specifies how many _bytes_ the passed string required to be written. Note that
bytes written is not the same as string characters. See [`Buffer.byteLength`][].
specifies how many _bytes_ the passed string required to be written. Bytes
written is not necessarily the same as string characters written. See
[`Buffer.byteLength`][].
Note that it is unsafe to use `fs.write` multiple times on the same file
without waiting for the callback. For this scenario,
`fs.createWriteStream` is strongly recommended.
It is unsafe to use `fs.write()` multiple times on the same file without waiting
for the callback. For this scenario, `fs.createWriteStream()` is recommended.
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
@ -3372,9 +3366,9 @@ fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback);
Any specified file descriptor has to support writing.
Note that it is unsafe to use `fs.writeFile` multiple times on the same file
without waiting for the callback. For this scenario,
`fs.createWriteStream` is strongly recommended.
It is unsafe to use `fs.writeFile()` multiple times on the same file without
waiting for the callback. For this scenario, `fs.createWriteStream()` is
recommended.
If a file descriptor is specified as the `file`, it will not be closed
automatically.
@ -4161,9 +4155,9 @@ Creates a symbolic link then resolves the `Promise` with no arguments upon
success.
The `type` argument is only used on Windows platforms and can be one of `'dir'`,
`'file'`, or `'junction'`. Note that Windows junction
points require the destination path to be absolute. When using `'junction'`,
the `target` argument will automatically be normalized to absolute path.
`'file'`, or `'junction'`. Windows junction points require the destination path
to be absolute. When using `'junction'`, the `target` argument will
automatically be normalized to absolute path.
### fsPromises.truncate(path[, len])
<!-- YAML
@ -4525,9 +4519,9 @@ string:
skipping the potentially stale local cache. It has a very real impact on
I/O performance so using this flag is not recommended unless it is needed.
Note that this doesn't turn `fs.open()` or `fsPromises.open()` into a
synchronous blocking call. If synchronous operation is desired, something
like `fs.openSync()` should be used.
This doesn't turn `fs.open()` or `fsPromises.open()` into a synchronous
blocking call. If synchronous operation is desired, something like
`fs.openSync()` should be used.
* `'w'` - Open file for writing.
The file is created (if it does not exist) or truncated (if it exists).