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