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
>From 4cf4784aafdf45fd3dec3855b9320d72dcd1a6ec Mon Sep 17 00:00:00 2001 From: Assaf Gordon <[email protected]> Date: Mon, 21 Apr 2014 14:31:23 -0400 Subject: [PATCH] stat: clarify mtime vs ctime in usage(), doc Change "modification time" to "data modification time", "change time" to "status change time". * src/stat.c: improve usage() * doc/coreutils.texi: add clarification paragraph --- doc/coreutils.texi | 19 +++++++++++++++---- src/stat.c | 8 ++++---- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 6c49385..e979c88 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -11829,10 +11829,10 @@ The valid @var{format} directives for files with @option{--format} and @item %W - Time of file birth as seconds since Epoch, or @samp{0} @item %x - Time of last access @item %X - Time of last access as seconds since Epoch -@item %y - Time of last modification -@item %Y - Time of last modification as seconds since Epoch -@item %z - Time of last change -@item %Z - Time of last change as seconds since Epoch +@item %y - Time of last data modification +@item %Y - Time of last data modification as seconds since Epoch +@item %z - Time of last status change +@item %Z - Time of last status change as seconds since Epoch @end itemize The @samp{%t} and @samp{%T} formats operate on the st_rdev member of @@ -11864,6 +11864,17 @@ precision: [1288929712.114951834] @end example +@emph{Access time} formats (@samp{%x},@samp{%X}) output the last time the +file was accessed for reading (if supported by the filesystem). Access time is +also shown with @command{ls -lu}. +@emph{Data modification} format (@samp{%y}, @samp{%Y}) +outputs the time the file's content was modified (e.g. by a program writing +to the file). Data modification time is also shown with @command{ls -l}. +@emph{Status change} format (@samp{%z},@samp{%Z}) outputs the +time the file's status was modified (e.g. owner, group, mode changes). Status +change time is also shown with @command{ls -lc}. + + The mount point printed by @samp{%m} is similar to that output by @command{df}, except that: @itemize @bullet diff --git a/src/stat.c b/src/stat.c index fffebe3..7d43eb5 100644 --- a/src/stat.c +++ b/src/stat.c @@ -1457,10 +1457,10 @@ The valid format sequences for files (without --file-system):\n\ %W time of file birth, seconds since Epoch; 0 if unknown\n\ %x time of last access, human-readable\n\ %X time of last access, seconds since Epoch\n\ - %y time of last modification, human-readable\n\ - %Y time of last modification, seconds since Epoch\n\ - %z time of last change, human-readable\n\ - %Z time of last change, seconds since Epoch\n\ + %y time of last data modification, human-readable\n\ + %Y time of last data modification, seconds since Epoch\n\ + %z time of last status change, human-readable\n\ + %Z time of last status change, seconds since Epoch\n\ \n\ "), stdout); -- 1.9.1
