stat: clarify mtime vs ctime [patch]

[Assaf Gordon]

Hello,

Would you be receptive to adding a tiny patch to 'stat' to clarify the 
difference between modification time and change time?

Currently, it simply says:
  %y   time of last modification, human-readable
  %Y   time of last modification, seconds since Epoch
  %z   time of last change, human-readable
  %Z   time of last change, seconds since Epoch

And for most non-unix experts, "last modification" is (almost) a synonym for "last 
change" (IMHO).

The patch changes:
  "modification" -> "data modification"
  "change" -> "status change"
And adds one clarification paragraph to the docs.

While this will not immediately resolve all questions, it will at least hint users which option 
they need (as "data" is different from "status").

The words "data" and "status" are also used (for mtime and ctime, respectively) 
in the POSIX pages of 'sys/stat.h':
http://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/stat.h.html


Perhaps, in addition, add a new FAQ ?
Something like:
====
Q. What is the difference between "access time", "data modification time" and 
"status change time" ?
A. Most UNIX systems keeps track of different times for each file.
"Access Time" keeps track of the last time a file was opened for reading.
"Data Modification time" keeps tracks of the last time file's content has been 
modified.
"Status Change time" keeps tracks of the last time a file's status (e.g. mode, 
owner, group, hard-links) was modified.

Configuration varies between filesystems - not all systems keep track of all 
three times.

To show "Access time", use "ls -lu" or stat's "%X" and "%x" formats.
To show "Data modification time", use "ls -l" or stat's "%Y" and "%y" formats.
To show "Status change time", use "ls -lc" or stat's "%Z" and "%z" formats.

Example:
    # Create a new file
    $ echo hello > test.txt

    # Show the file's time stamps
    $ stat --printf "Access: %x\nModify: %y\nChange: %z\n" test.txt
    Access: 2014-04-21 14:01:00.131648000 +0000
    Modify: 2014-04-21 14:01:00.131648000 +0000
    Change: 2014-04-21 14:01:00.131648000 +0000

    # Wait 5 seconds, then update the file's content.
    # NOTE: Status change time is also updated.
    $ sleep 5 ; echo world >> test.txt
    $ stat --printf "Access: %x\nModify: %y\nChange: %z\n" test.txt
    Access: 2014-04-21 14:01:00.131648000 +0000
    Modify: 2014-04-21 14:01:05.161657000 +0000
    Change: 2014-04-21 14:01:05.161657000 +0000

    # Wait 5 seconds, then update the file's status (but not content)
    $ sleep 5 ; chmod o-rwx test.txt
    $ stat --printf "Access: %x\nModify: %y\nChange: %z\n" test.txt
    Access: 2014-04-21 14:01:00.131648000 +0000
    Modify: 2014-04-21 14:01:05.161657000 +0000
    Change: 2014-04-21 14:01:10.250232749 +0000

    # Wait 5 seconds, then read (access) the file's content
    $ sleep 5 ; wc test.txt > /dev/null
    $ stat --printf "Access: %x\nModify: %y\nChange: %z\n" test.txt
    Access: 2014-04-21 14:01:15.298241904 +0000
    Modify: 2014-04-21 14:01:05.161657000 +0000
    Change: 2014-04-21 14:01:10.250232749 +0000

    # Show Data Modification time with 'ls -l'
    $  ls --full-time -log test.txt
    -rw-r----- 1 12 2014-04-21 14:01:05.161657000 +0000 test.txt

    # Show Status Change time with 'ls -c'
    $ ls --full-time -log -c test.txt
    -rw-r----- 1 12 2014-04-21 14:01:10.250232749 +0000 test.txt

    # Show Last Access time with 'ls -u'
    $ ls --full-time -log -u test.txt
    -rw-r----- 1 12 2014-04-21 14:01:15.298241904 +0000 test.txt



Regards,
 -gordon

stat_mtime_ctime2.patch
Description: Text Data