From a79dece8aded7891cb64b9d87c0a9ba26aa7c9c4 Mon Sep 17 00:00:00 2001 From: Tyler Anton Date: Sat, 7 Mar 2015 21:52:18 -0500 Subject: [PATCH] docs: add return value for sync fs functions Clarify that synchronous functions in fs with no return value return undefined. Specify that fs.openSync() returns an integer and fs.existsSync() returns true or false. Fixes: https://github.com/joyent/node/issues/9313 PR: https://github.com/joyent/node/pull/9359 Reviewed-By: Julien Gilli PORT-FROM: joyent/node @ 51fe319faf4399fd027f8b32d1c425200b911e44 PR-URL: https://github.com/nodejs/io.js/pull/1770 Reviewed-By: Roman Reiss Reviewed-By: Jeremiah Senkpiel Conflicts: doc/api/fs.markdown --- doc/api/fs.markdown | 51 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 21 deletions(-) diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 3b85d78..e16f72c 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -92,7 +92,7 @@ to the completion callback. ## fs.renameSync(oldPath, newPath) -Synchronous rename(2). +Synchronous rename(2). Returns `undefined`. ## fs.ftruncate(fd, len, callback) @@ -101,7 +101,7 @@ given to the completion callback. ## fs.ftruncateSync(fd, len) -Synchronous ftruncate(2). +Synchronous ftruncate(2). Returns `undefined`. ## fs.truncate(path, len, callback) @@ -111,7 +111,7 @@ first argument. In this case, `fs.ftruncate()` is called. ## fs.truncateSync(path, len) -Synchronous truncate(2). +Synchronous truncate(2). Returns `undefined`. ## fs.chown(path, uid, gid, callback) @@ -120,7 +120,7 @@ to the completion callback. ## fs.chownSync(path, uid, gid) -Synchronous chown(2). +Synchronous chown(2). Returns `undefined`. ## fs.fchown(fd, uid, gid, callback) @@ -129,7 +129,7 @@ to the completion callback. ## fs.fchownSync(fd, uid, gid) -Synchronous fchown(2). +Synchronous fchown(2). Returns `undefined`. ## fs.lchown(path, uid, gid, callback) @@ -138,7 +138,7 @@ to the completion callback. ## fs.lchownSync(path, uid, gid) -Synchronous lchown(2). +Synchronous lchown(2). Returns `undefined`. ## fs.chmod(path, mode, callback) @@ -147,7 +147,7 @@ to the completion callback. ## fs.chmodSync(path, mode) -Synchronous chmod(2). +Synchronous chmod(2). Returns `undefined`. ## fs.fchmod(fd, mode, callback) @@ -156,7 +156,7 @@ are given to the completion callback. ## fs.fchmodSync(fd, mode) -Synchronous fchmod(2). +Synchronous fchmod(2). Returns `undefined`. ## fs.lchmod(path, mode, callback) @@ -167,7 +167,7 @@ Only available on Mac OS X. ## fs.lchmodSync(path, mode) -Synchronous lchmod(2). +Synchronous lchmod(2). Returns `undefined`. ## fs.stat(path, callback) @@ -207,7 +207,7 @@ the completion callback. ## fs.linkSync(srcpath, dstpath) -Synchronous link(2). +Synchronous link(2). Returns `undefined`. ## fs.symlink(destination, path[, type], callback) @@ -220,7 +220,7 @@ Note that Windows junction points require the destination path to be absolute. ## fs.symlinkSync(destination, path[, type]) -Synchronous symlink(2). +Synchronous symlink(2). Returns `undefined`. ## fs.readlink(path, callback) @@ -257,7 +257,7 @@ to the completion callback. ## fs.unlinkSync(path) -Synchronous unlink(2). +Synchronous unlink(2). Returns `undefined`. ## fs.rmdir(path, callback) @@ -266,7 +266,7 @@ to the completion callback. ## fs.rmdirSync(path) -Synchronous rmdir(2). +Synchronous rmdir(2). Returns `undefined`. ## fs.mkdir(path[, mode], callback) @@ -275,7 +275,7 @@ to the completion callback. `mode` defaults to `0o777`. ## fs.mkdirSync(path[, mode]) -Synchronous mkdir(2). +Synchronous mkdir(2). Returns `undefined`. ## fs.readdir(path, callback) @@ -295,7 +295,7 @@ to the completion callback. ## fs.closeSync(fd) -Synchronous close(2). +Synchronous close(2). Returns `undefined`. ## fs.open(path, flags[, mode], callback) @@ -356,19 +356,27 @@ the end of the file. ## fs.openSync(path, flags[, mode]) -Synchronous version of `fs.open()`. +Synchronous version of `fs.open()`. Returns an integer representing the file +descriptor. ## fs.utimes(path, atime, mtime, callback) -## fs.utimesSync(path, atime, mtime) Change file timestamps of the file referenced by the supplied path. +## fs.utimesSync(path, atime, mtime) + +Synchronous version of `fs.utimes()`. Returns `undefined`. + + ## fs.futimes(fd, atime, mtime, callback) -## fs.futimesSync(fd, atime, mtime) 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.fsync(fd, callback) Asynchronous fsync(2). No arguments other than a possible exception are given @@ -376,7 +384,7 @@ to the completion callback. ## fs.fsyncSync(fd) -Synchronous fsync(2). +Synchronous fsync(2). Returns `undefined`. ## fs.write(fd, buffer, offset, length[, position], callback) @@ -514,7 +522,7 @@ If `options` is a string, then it specifies the encoding. Example: ## fs.writeFileSync(filename, data[, options]) -The synchronous version of `fs.writeFile`. +The synchronous version of `fs.writeFile`. Returns `undefined`. ## fs.appendFile(filename, data[, options], callback) @@ -542,7 +550,7 @@ If `options` is a string, then it specifies the encoding. Example: ## fs.appendFileSync(filename, data[, options]) -The synchronous version of `fs.appendFile`. +The synchronous version of `fs.appendFile`. Returns `undefined`. ## fs.watchFile(filename[, options], listener) @@ -680,6 +688,7 @@ and handle the error when it's not there. ## fs.existsSync(path) Synchronous version of [`fs.exists`](fs.html#fs_fs_exists_path_callback). +Returns `true` if the file exists, `false` otherwise. `fs.existsSync()` is **deprecated**. For supported alternatives please check out [`fs.statSync`](fs.html#fs_fs_statsync_path) or -- 2.7.4