fs: Expose birthtime on stat objects

Just do the best we can with whatever libuv gives us.

Also, document the semantics of `ctime` and the compatibility with
Windows.

Author: isaacs

doc/api/fs.markdown

@@ -672,21 +672,45 @@ similar to this:
       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.
+      ctime: Mon, 10 Oct 2011 23:24:11 GMT,
+      birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
+
+Please note that `atime`, `mtime`, `birthtime`, 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
 
+### Stat Time Values
+
+The times in the stat object have the following semantics:
+
+* `atime` "Access Time" - Time when file data last accessed.  Changed
+  by the `mknod(2)`, `utimes(2)`, and `read(2)` system calls.
+* `mtime` "Modified Time" - Time when file data last modified.
+  Changed by the `mknod(2)`, `utimes(2)`, and `write(2)` system calls.
+* `ctime` "Change Time" - Time when file status was last changed
+  (inode data modification).  Changed by the `chmod(2)`, `chown(2)`,
+  `link(2)`, `mknod(2)`, `rename(2)`, `unlink(2)`, `utimes(2)`,
+  `read(2)`, and `write(2)` system calls.
+* `birthtime` "Birth Time" -  Time of file creation. Set once when the
+  file is created.  On filesystems where birthtime is not available,
+  this field may instead hold either the `ctime` or
+  `1970-01-01T00:00Z` (ie, unix epoch timestamp `0`).  On Darwin and
+  other FreeBSD variants, also set if the `atime` is explicitly set to
+  an earlier value than the current `birthtime` using the `utimes(2)`
+  system call.
+
+Prior to Node v0.12, the `ctime` held the `birthtime` on Windows
+systems.  Note that as of v0.12, `ctime` is not "creation time", and
+on Unix systems, it never was.
 
 ## fs.createReadStream(path, [options])
 

src/node_file.cc

@@ -286,6 +286,7 @@ static Cached<String> blocks_symbol;
 static Cached<String> atime_symbol;
 static Cached<String> mtime_symbol;
 static Cached<String> ctime_symbol;
+static Cached<String> birthtime_symbol;
 
 Local<Object> BuildStatsObject(const uv_stat_t* s) {
   HandleScope scope(node_isolate);
@@ -304,6 +305,7 @@ Local<Object> BuildStatsObject(const uv_stat_t* s) {
     atime_symbol = FIXED_ONE_BYTE_STRING(node_isolate, "atime");
     mtime_symbol = FIXED_ONE_BYTE_STRING(node_isolate, "mtime");
     ctime_symbol = FIXED_ONE_BYTE_STRING(node_isolate, "ctime");
+    birthtime_symbol = FIXED_ONE_BYTE_STRING(node_isolate, "birthtime");
   }
 
   Local<Function> constructor =
@@ -363,6 +365,7 @@ Local<Object> BuildStatsObject(const uv_stat_t* s) {
   X(atime, atim)
   X(mtime, mtim)
   X(ctime, ctim)
+  X(birthtime, birthtim)
 #undef X
 
   return scope.Close(stats);