diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 7ebf052508..b17669088a 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -133,23 +133,8 @@ Synchronous lchmod(2). ### fs.stat(path, [callback]) Asynchronous stat(2). The callback gets two arguments `(err, stats)` where -`stats` is a [`fs.Stats`](#fs.Stats) object. It looks like this: - - { dev: 2049, - ino: 305352, - mode: 16877, - nlink: 12, - uid: 1000, - gid: 1000, - rdev: 0, - size: 4096, - blksize: 4096, - blocks: 8, - atime: '2009-06-29T11:11:55Z', - mtime: '2009-06-29T11:11:40Z', - ctime: '2009-06-29T11:11:40Z' } - -See the [fs.Stats](#fs.Stats) section below for more information. +`stats` is a [`fs.Stats`](#fs.Stats) object. See the [fs.Stats](#fs.Stats) +section below for more information. ### fs.lstat(path, [callback]) @@ -266,7 +251,7 @@ Asynchronous file open. See open(2). `flags` can be: * `'r'` - Open file for reading. An exception occurs if the file does not exist. -* `'r+'` - Open file for reading and writing. +* `'r+'` - Open file for reading and writing. An exception occurs if the file does not exist. * `'w'` - Open file for writing. @@ -457,7 +442,8 @@ callback, and have some fallback logic if it is null. ## fs.Stats -Objects returned from `fs.stat()` and `fs.lstat()` are of this type. +Objects returned from `fs.stat()`, `fs.lstat()` and `fs.fstat()` and their +synchronous counterparts are of this type. - `stats.isFile()` - `stats.isDirectory()` @@ -467,6 +453,35 @@ Objects returned from `fs.stat()` and `fs.lstat()` are of this type. - `stats.isFIFO()` - `stats.isSocket()` +For a regular file `sys.inspect(stats)` would return a string very +similar to this: + + { dev: 2114, + ino: 48064969, + mode: 33188, + nlink: 1, + uid: 85, + gid: 100, + rdev: 0, + size: 527, + blksize: 4096, + blocks: 8, + atime: Mon, 10 Oct 2011 23:24:11 GMT, + mtime: Mon, 10 Oct 2011 23:24:11 GMT, + ctime: Mon, 10 Oct 2011 23:24:11 GMT } + +Please note that `atime`, `mtime` and `ctime` are instances +of [`Date`][MDN-Date] object and to compare the values of +these objects you should use appropriate methods. For most +general uses [`getTime()`][MDN-Date-getTime] will return +the number of milliseconds elapsed since _1 January 1970 +00:00:00 UTC_ and this integer should be sufficient for +any comparison, however there additional methods which can +be used for displaying fuzzy information. More details can +be found in the [MDN JavaScript Reference][MDN-Date] page. + +[MDN-Date]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date +[MDN-Date-getTime]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/getTime ## fs.ReadStream