From 1aa955a3b5e0f1dce5c5a7f99a2a3c7f3bcdc9b5 Mon Sep 17 00:00:00 2001 From: Jenna Vuong Date: Sun, 1 May 2016 00:58:16 -0700 Subject: [PATCH 1/3] doc: adds 'close' events to fs.ReadStream and fs.WriteStream Add 'close' event to doc/api/fs.md --> fs.ReadStream Add 'close' event to doc/api/fs.md --> fs.WriteStream Add 'close event to doc/api/stream.md --> stream.Writable From squashed history: Add 'close' event to stream.Writable per Issue #6484 Add #### prefix to Event: 'close' and backticks to 'close' similar to stream.Readable event: 'close' section Add more specifics to 'close' events for fs.ReadStream and fs.WriteStream Fix/Changed 'close' event from 'fs.ReadStream' to 'fs.WriteStream' wrapped long lines at 80 chars, reworded per Issue #6484 including the 'close' event as optional add 'close' event as optional in stream.Readable per issue #6484 doc: Add 'close' events to fs.ReadStream, 80char nit Fixes: #6484 PR-URL: https://github.com/nodejs/node/pull/6499 Reviewed-By: James M Snell Reviewed-By: Brian White Reviewed-By: Anna Henningsen Reviewed-By: Robert Jefe Lindstaedt --- doc/api/fs.md | 10 ++++++++++ doc/api/stream.md | 12 +++++++++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 0daf2e5f5d0879..c3c3fd669dc59a 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -126,6 +126,11 @@ Stop watching for changes on the given `fs.FSWatcher`. Emitted when the ReadStream's file is opened. +### Event: 'close' + +Emitted when the `ReadStream`'s underlying file descriptor has been closed +using the `fs.close()` method. + ### readStream.path The path to the file the stream is reading from. @@ -210,6 +215,11 @@ on Unix systems, it never was. Emitted when the WriteStream's file is opened. +### Event: 'close' + +Emitted when the `WriteStream`'s underlying file descriptor has been closed +using the `fs.close()` method. + ### writeStream.bytesWritten The number of bytes written so far. Does not include data that is still queued diff --git a/doc/api/stream.md b/doc/api/stream.md index 37ea2a4b1fce83..c2cf1d4f5a79e4 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -160,7 +160,8 @@ Emitted when the stream and any of its underlying resources (a file descriptor, for example) have been closed. The event indicates that no more events will be emitted, and no further computation will occur. -Not all streams will emit the `'close'` event. +Not all streams will emit the `'close'` event as the `'close'` event is +optional. #### Event: 'data' @@ -573,6 +574,15 @@ Examples of writable streams include: * [child process stdin][] * [`process.stdout`][], [`process.stderr`][] +#### Event: 'close' + +Emitted when the stream and any of its underlying resources (a file descriptor, +for example) have been closed. The event indicates that no more events will be +emitted, and no further computation will occur. + +Not all streams will emit the `'close'` event as the `'close'` event is +optional. + #### Event: 'drain' If a [`stream.write(chunk)`][stream-write] call returns `false`, then the From 3c398de65bcd5e1a79a8e663de31ad32ba0a6b08 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Thu, 12 May 2016 20:52:39 +0200 Subject: [PATCH 2/3] doc: add `added:` information for fs Ref: https://github.com/nodejs/node/issues/6578 PR-URL: https://github.com/nodejs/node/pull/6717 Reviewed-By: Robert Lindstaedt Reviewed-By: James M Snell --- doc/api/fs.md | 263 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) diff --git a/doc/api/fs.md b/doc/api/fs.md index c3c3fd669dc59a..166ad6a63e033b 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -95,10 +95,16 @@ Error: EISDIR, read ``` ## Class: fs.FSWatcher + Objects returned from `fs.watch()` are of this type. ### Event: 'change' + * `event` {String} The type of fs change * `filename` {String} The filename that changed (if relevant/available) @@ -107,35 +113,56 @@ Emitted when something changes in a watched directory or file. See more details in [`fs.watch()`][]. ### Event: 'error' + * `error` {Error} Emitted when an error occurs. ### watcher.close() + Stop watching for changes on the given `fs.FSWatcher`. ## Class: fs.ReadStream + `ReadStream` is a [Readable Stream][]. ### Event: 'open' + * `fd` {Number} Integer file descriptor used by the ReadStream. Emitted when the ReadStream's file is opened. ### Event: 'close' + Emitted when the `ReadStream`'s underlying file descriptor has been closed using the `fs.close()` method. ### readStream.path + The path to the file the stream is reading from. ## Class: fs.Stats + Objects returned from [`fs.stat()`][], [`fs.lstat()`][] and [`fs.fstat()`][] and their synchronous counterparts are of this type. @@ -206,30 +233,48 @@ systems. Note that as of v0.12, `ctime` is not "creation time", and on Unix systems, it never was. ## Class: fs.WriteStream + `WriteStream` is a [Writable Stream][]. ### Event: 'open' + * `fd` {Number} Integer file descriptor used by the WriteStream. Emitted when the WriteStream's file is opened. ### Event: 'close' + Emitted when the `WriteStream`'s underlying file descriptor has been closed using the `fs.close()` method. ### writeStream.bytesWritten + The number of bytes written so far. Does not include data that is still queued for writing. ### writeStream.path + The path to the file the stream is writing to. ## fs.access(path[, mode], callback) + Tests a user's permissions for the file specified by `path`. `mode` is an optional integer that specifies the accessibility checks to be performed. The @@ -256,11 +301,17 @@ fs.access('/etc/passwd', fs.R_OK | fs.W_OK, (err) => { ``` ## fs.accessSync(path[, mode]) + Synchronous version of [`fs.access()`][]. This throws if any accessibility checks fail, and does nothing otherwise. ## fs.appendFile(file, data[, options], callback) + * `file` {String} filename * `data` {String|Buffer} @@ -289,37 +340,61 @@ fs.appendFile('message.txt', 'data to append', 'utf8', callback); ``` ## fs.appendFileSync(file, data[, options]) + The synchronous version of [`fs.appendFile()`][]. Returns `undefined`. ## fs.chmod(path, mode, callback) + Asynchronous chmod(2). No arguments other than a possible exception are given to the completion callback. ## fs.chmodSync(path, mode) + Synchronous chmod(2). Returns `undefined`. ## fs.chown(path, uid, gid, callback) + Asynchronous chown(2). No arguments other than a possible exception are given to the completion callback. ## fs.chownSync(path, uid, gid) + Synchronous chown(2). Returns `undefined`. ## fs.close(fd, callback) + Asynchronous close(2). No arguments other than a possible exception are given to the completion callback. ## fs.closeSync(fd) + Synchronous close(2). Returns `undefined`. ## fs.createReadStream(path[, options]) + Returns a new [`ReadStream`][] object. (See [Readable Stream][]). @@ -366,6 +441,9 @@ fs.createReadStream('sample.txt', {start: 90, end: 99}); If `options` is a string, then it specifies the encoding. ## fs.createWriteStream(path[, options]) + Returns a new [`WriteStream`][] object. (See [Writable Stream][]). @@ -393,6 +471,10 @@ Like [`ReadStream`][], if `fd` is specified, `WriteStream` will ignore the If `options` is a string, then it specifies the encoding. ## fs.exists(path, callback) + Stability: 0 - Deprecated: Use [`fs.stat()`][] or [`fs.access()`][] instead. @@ -412,6 +494,10 @@ call `fs.open()` directly and handle the error raised if the file is non-existent. ## fs.existsSync(path) + Stability: 0 - Deprecated: Use [`fs.statSync()`][] or [`fs.accessSync()`][] instead. @@ -419,70 +505,115 @@ Synchronous version of [`fs.exists()`][]. Returns `true` if the file exists, `false` otherwise. ## fs.fchmod(fd, mode, callback) + Asynchronous fchmod(2). No arguments other than a possible exception are given to the completion callback. ## fs.fchmodSync(fd, mode) + Synchronous fchmod(2). Returns `undefined`. ## fs.fchown(fd, uid, gid, callback) + Asynchronous fchown(2). No arguments other than a possible exception are given to the completion callback. ## fs.fchownSync(fd, uid, gid) + Synchronous fchown(2). Returns `undefined`. ## fs.fdatasync(fd, callback) + Asynchronous fdatasync(2). No arguments other than a possible exception are given to the completion callback. ## fs.fdatasyncSync(fd) + Synchronous fdatasync(2). Returns `undefined`. ## fs.fstat(fd, callback) + Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where `stats` is a [`fs.Stats`][] object. `fstat()` is identical to [`stat()`][], except that the file to be stat-ed is specified by the file descriptor `fd`. ## fs.fstatSync(fd) + Synchronous fstat(2). Returns an instance of `fs.Stats`. ## fs.fsync(fd, callback) + Asynchronous fsync(2). No arguments other than a possible exception are given to the completion callback. ## fs.fsyncSync(fd) + Synchronous fsync(2). Returns `undefined`. ## fs.ftruncate(fd, len, callback) + Asynchronous ftruncate(2). No arguments other than a possible exception are given to the completion callback. ## fs.ftruncateSync(fd, len) + Synchronous ftruncate(2). Returns `undefined`. ## fs.futimes(fd, atime, mtime, callback) + Change the file timestamps of a file referenced by the supplied file descriptor. ## fs.futimesSync(fd, atime, mtime) + Synchronous version of [`fs.futimes()`][]. Returns `undefined`. ## fs.lchmod(path, mode, callback) + Asynchronous lchmod(2). No arguments other than a possible exception are given to the completion callback. @@ -490,28 +621,46 @@ are given to the completion callback. Only available on Mac OS X. ## fs.lchmodSync(path, mode) + Synchronous lchmod(2). Returns `undefined`. ## fs.lchown(path, uid, gid, callback) + Asynchronous lchown(2). No arguments other than a possible exception are given to the completion callback. ## fs.lchownSync(path, uid, gid) + Synchronous lchown(2). Returns `undefined`. ## fs.link(srcpath, dstpath, callback) + Asynchronous link(2). No arguments other than a possible exception are given to the completion callback. ## fs.linkSync(srcpath, dstpath) + Synchronous link(2). Returns `undefined`. ## fs.lstat(path, callback) + Asynchronous lstat(2). The callback gets two arguments `(err, stats)` where `stats` is a [`fs.Stats`][] object. `lstat()` is identical to `stat()`, @@ -519,19 +668,31 @@ except that if `path` is a symbolic link, then the link itself is stat-ed, not the file that it refers to. ## fs.lstatSync(path) + Synchronous lstat(2). Returns an instance of `fs.Stats`. ## fs.mkdir(path[, mode], callback) + Asynchronous mkdir(2). No arguments other than a possible exception are given to the completion callback. `mode` defaults to `0o777`. ## fs.mkdirSync(path[, mode]) + Synchronous mkdir(2). Returns `undefined`. ## fs.open(path, flags[, mode], callback) + Asynchronous file open. See open(2). `flags` can be: @@ -594,11 +755,17 @@ The kernel ignores the position argument and always appends the data to the end of the file. ## fs.openSync(path, flags[, mode]) + Synchronous version of [`fs.open()`][]. Returns an integer representing the file descriptor. ## fs.read(fd, buffer, offset, length, position, callback) + Read data from the file specified by `fd`. @@ -614,17 +781,26 @@ If `position` is `null`, data will be read from the current file position. The callback is given the three arguments, `(err, bytesRead, buffer)`. ## fs.readdir(path, callback) + Asynchronous readdir(3). Reads the contents of a directory. The callback gets two arguments `(err, files)` where `files` is an array of the names of the files in the directory excluding `'.'` and `'..'`. ## fs.readdirSync(path) + Synchronous readdir(3). Returns an array of filenames excluding `'.'` and `'..'`. ## fs.readFile(file[, options], callback) + * `file` {String} filename * `options` {Object | String} @@ -653,6 +829,9 @@ fs.readFile('/etc/passwd', 'utf8', callback); ``` ## fs.readFileSync(file[, options]) + Synchronous version of [`fs.readFile`][]. Returns the contents of the `file`. @@ -660,15 +839,24 @@ If the `encoding` option is specified then this function returns a string. Otherwise it returns a buffer. ## fs.readlink(path, callback) + Asynchronous readlink(2). The callback gets two arguments `(err, linkString)`. ## fs.readlinkSync(path) + Synchronous readlink(2). Returns the symbolic link's string value. ## fs.realpath(path[, cache], callback) + Asynchronous realpath(2). The `callback` gets two arguments `(err, resolvedPath)`. May use `process.cwd` to resolve relative paths. `cache` is an @@ -686,44 +874,71 @@ fs.realpath('/etc/passwd', cache, (err, resolvedPath) => { ``` ## fs.readSync(fd, buffer, offset, length, position) + Synchronous version of [`fs.read()`][]. Returns the number of `bytesRead`. ## fs.realpathSync(path[, cache]) + Synchronous realpath(2). Returns the resolved path. `cache` is an object literal of mapped paths that can be used to force a specific path resolution or avoid additional `fs.stat` calls for known real paths. ## fs.rename(oldPath, newPath, callback) + Asynchronous rename(2). No arguments other than a possible exception are given to the completion callback. ## fs.renameSync(oldPath, newPath) + Synchronous rename(2). Returns `undefined`. ## fs.rmdir(path, callback) + Asynchronous rmdir(2). No arguments other than a possible exception are given to the completion callback. ## fs.rmdirSync(path) + Synchronous rmdir(2). Returns `undefined`. ## fs.stat(path, callback) + Asynchronous stat(2). The callback gets two arguments `(err, stats)` where `stats` is a [`fs.Stats`][] object. See the [`fs.Stats`][] section for more information. ## fs.statSync(path) + Synchronous stat(2). Returns an instance of [`fs.Stats`][]. ## fs.symlink(target, path[, type], callback) + Asynchronous symlink(2). No arguments other than a possible exception are given to the completion callback. @@ -741,29 +956,47 @@ fs.symlink('./foo', './new-port'); It creates a symbolic link named "new-port" that points to "foo". ## fs.symlinkSync(target, path[, type]) + Synchronous symlink(2). Returns `undefined`. ## fs.truncate(path, len, callback) + Asynchronous truncate(2). No arguments other than a possible exception are given to the completion callback. A file descriptor can also be passed as the first argument. In this case, `fs.ftruncate()` is called. ## fs.truncateSync(path, len) + Synchronous truncate(2). Returns `undefined`. ## fs.unlink(path, callback) + Asynchronous unlink(2). No arguments other than a possible exception are given to the completion callback. ## fs.unlinkSync(path) + Synchronous unlink(2). Returns `undefined`. ## fs.unwatchFile(filename[, listener]) + Stop watching for changes on `filename`. If `listener` is specified, only that particular listener is removed. Otherwise, *all* listeners are removed and you @@ -777,6 +1010,9 @@ _Note: [`fs.watch()`][] is more efficient than `fs.watchFile()` and `fs.unwatchF when possible._ ## fs.utimes(path, atime, mtime, callback) + Change file timestamps of the file referenced by the supplied path. @@ -789,10 +1025,16 @@ follow the below rules: `Date.now()`. ## fs.utimesSync(path, atime, mtime) + Synchronous version of [`fs.utimes()`][]. Returns `undefined`. ## fs.watch(filename[, options][, listener]) + Watch for changes on `filename`, where `filename` is either a file or a directory. The returned object is a [`fs.FSWatcher`][]. @@ -873,6 +1115,9 @@ fs.watch('somedir', (event, filename) => { ``` ## fs.watchFile(filename[, options], listener) + Watch for changes on `filename`. The callback `listener` will be called each time the file is accessed. @@ -910,6 +1155,9 @@ _Note: [`fs.watch()`][] is more efficient than `fs.watchFile` and `fs.unwatchFil when possible._ ## fs.write(fd, buffer, offset, length[, position], callback) + Write `buffer` to the file specified by `fd`. @@ -931,6 +1179,9 @@ The kernel ignores the position argument and always appends the data to the end of the file. ## fs.write(fd, data[, position[, encoding]], callback) + Write `data` to the file specified by `fd`. If `data` is not a Buffer instance then the value will be coerced to a string. @@ -958,6 +1209,9 @@ The kernel ignores the position argument and always appends the data to the end of the file. ## fs.writeFile(file, data[, options], callback) + * `file` {String} filename * `data` {String | Buffer} @@ -993,12 +1247,21 @@ without waiting for the callback. For this scenario, `fs.createWriteStream` is strongly recommended. ## fs.writeFileSync(file, data[, options]) + The synchronous version of [`fs.writeFile()`][]. Returns `undefined`. ## fs.writeSync(fd, buffer, offset, length[, position]) + ## fs.writeSync(fd, data[, position[, encoding]]) + Synchronous versions of [`fs.write()`][]. Returns the number of bytes written. From cb8fae67691a5f1cc8277fcdd81836bb104cf747 Mon Sep 17 00:00:00 2001 From: Richard Lau Date: Tue, 14 Jun 2016 15:57:22 -0400 Subject: [PATCH 3/3] doc: correct `added:` information for fs.access fs.access and fs.accessSync were added to Node v0.11.15 via 2944934 PR-URL: https://github.com/nodejs/node/pull/7299 Reviewed-By: Anna Henningsen Ref: https://github.com/nodejs/node/pull/6717 Ref: https://github.com/nodejs/node/issues/6578 --- doc/api/fs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 166ad6a63e033b..f0910d24892907 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -273,7 +273,7 @@ The path to the file the stream is writing to. ## fs.access(path[, mode], callback) Tests a user's permissions for the file specified by `path`. `mode` is an @@ -302,7 +302,7 @@ fs.access('/etc/passwd', fs.R_OK | fs.W_OK, (err) => { ## fs.accessSync(path[, mode]) Synchronous version of [`fs.access()`][]. This throws if any accessibility checks