Re: stat: clarify mtime vs ctime [patch]

[Pádraig Brady]

On 04/21/2014 08:14 PM, Assaf Gordon wrote:
> 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.

This clarification is worth making, thanks!

> 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

I might have gone with "attributes" rather than "status",
but given the above references, "status" is fine I think.

> Perhaps, in addition, add a new FAQ ?

Let's avoid the FAQ for the moment.
Hopefully the improved docs will avoid the need.

>>From 4cf4784aafdf45fd3dec3855b9320d72dcd1a6ec Mon Sep 17 00:00:00 2001
> From: Assaf Gordon <address@hidden>
> Date: Mon, 21 Apr 2014 14:31:23 -0400
> Subject: [PATCH] stat: clarify mtime vs ctime in usage(), doc

s/stat:/doc:/

> +@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}.

s/filesystem/file system/ for consistency, but
if the file was just opened for reading, then access time isn't updated,
only if data is read. Also for performance reasons, modern Linux systems
only update atime if it's older than [cm]time.
I.E. with relatime enabled, it's really only an indicator
as to whether the file has been read since it was last updated.
So I think this whole block might add more ambiguity than
any additional clarification. OK to drop this block?

> 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\

+1 to this part.

thanks,
Pádraig.