From 1e9d27cbccd350e12c7bc661c5be1b94aa89895b Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Thu, 12 May 2016 20:52:39 +0200 Subject: [PATCH] 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.