Subject: bug#32250: ls -explain better the different times

From: Assaf Gordon <[email-masked]>
Date: Sun, 30 Dec 2018 21:13:30 -0700

Hello,

On 2018-07-23 9:54 a.m., kalle wrote:
> in the documentation of ls the concept of the different times is not
> explained sufficiently well (mtime, atime, ctime).

The dedicated file-timestamp section (
https://www.gnu.org/software/coreutils/manual/html_node/File-timestamps.html 
) is indeed perhaps a bit too dense (lots of text
with no quick examples).

Attached is an improvement suggestion, adding a summary table,
and details examples.

Comments and feedback welcomed,
  - assaf

>From f5774f87df4af912fd826f3d4208c9cd766e7524 Mon Sep 17 00:00:00 2001
From: Assaf Gordon <[email-masked]>
Date: Sun, 30 Dec 2018 20:28:28 -0700
Subject: [PATCH] doc: expand file timestamp section (atime,ctime,mtime)

Requested by kalle <[email-masked]> in
https://bugs.gnu.org/32250 .

* doc/coreutils.texi (File timestamps): Add summary table and examples.
---
 doc/coreutils.texi | 279 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 279 insertions(+)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index fd6d578ac..56831e46a 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -18877,6 +18877,132 @@ copy of the file, including the new permissions value.  Another
 operation that modifies a file's ctime without affecting the others is
 renaming.
 
+@multitable @columnfractions .25 .25 .25 .25
+
+@headitem
+@tab Access Time
+@tab Modify Time
+@tab Change Time
+
+@item abbreviation
+@tab @code{atime}
+@tab @code{mtime}
+@tab @code{ctime}
+
+@item Updated when
+@tab content read
+@tab content modified
+@tab meta-data modified @*(e.g., permissions, owner, file name)
+
+@headitem Files @c{second line in next headitem}
+@tab Access Time
+@tab Modify Time
+@tab Change Time
+
+@headitem Affected by:
+
+@item @command{touch}
+@tab yes
+@tab yes
+@tab yes
+
+@item @command{touch -a}
+@tab yes
+@tab no
+@tab yes
+
+@item @command{touch -m}
+@tab no
+@tab yes
+@tab yes
+
+@item @command{chmod}
+@tab no
+@tab no
+@tab yes
+
+@item @command{chown}
+@tab no
+@tab no
+@tab yes
+
+@item @command{mv}
+@tab no
+@tab no
+@tab yes
+
+@headitem Directories @*Affected by:
+
+@item Listing files
+@tab yes
+@tab no
+@tab no
+
+@item Creating a new file
+@tab no
+@tab yes
+@tab yes
+
+@item Renaming a file
+@tab no
+@tab yes
+@tab yes
+
+@item meta-data changes to a file inside the directory
+@tab no
+@tab no
+@tab no
+
+
+@headitem @c{add a space for cleaner visuals }
+
+@headitem Running @command{cp SRC DST}:
+@tab Access Time
+@tab Modify Time
+@tab Change Time
+
+@item Changes to @file{SRC}
+@tab yes
+@tab no
+@tab no
+
+@item Changes to @file{DST}
+@tab yes
+@tab yes
+@tab yes
+
+@headitem Running @*@command{cp -p SRC DST}:
+@item Changes to @file{SRC}
+@tab no
+@tab no
+@tab no
+
+@item Changes to @file{DST}
+@tab (same as @file{SRC})
+@tab (same as @file{SRC})
+@tab yes @* (set to current time)
+
+@headitem Displaying timestamps
+@item Show with @command{ls} option
+@tab @option{-l -u}
+@tab @option{-l}
+@tab @option{-l -c}
+
+@item @command{stat} @option{-c} format @*(human readable)
+@tab @option{%x}
+@tab @option{%y}
+@tab @option{%z}
+
+@item @command{stat} @option{-c} format @*(seconds since epoch)
+@tab @option{%X}
+@tab @option{%Y}
+@tab @option{%Z}
+
+@end multitable
+
+@*
+@*
+
 Naively, a file's atime, mtime, and ctime are set to the current time
 whenever you read, write, or change the attributes of the file
 respectively, and searching a directory counts as reading it.  A
@@ -18920,6 +19046,159 @@ and microsecond resolution for the primitive that @command{touch} uses
 to set a file's timestamp to an arbitrary value.

+@unnumberedsec Timestamp examples
+
+These two shell functions (@code{lstime} and @code{stattime}) will be
+used in the following examples to show the three timestamps (access, modify,
+change times) of a file:
+
+@example
+lstime()
+@{
+  printf "Access (read): " ; ls -log -u "$1" ;
+  printf "Modify (data): " ; ls -log    "$1" ;
+  printf "Change (meta): " ; ls -log -c "$1" ;
+@}
+
+stattime()
+@{
+  stat --printf "File name:  %n\n"     "$1" ;
+  stat --printf " Access (read): %x\n" "$1" ;
+  stat --printf " Modify (data): %y\n" "$1" ;
+  stat --printf " Change (meta): %z\n" "$1" ;
+@}
+@end example
+
+@iftex
+@exdent
+@end iftex
+Starting with an empty directory, create a new file (@file{myfile})
+then examine its time stamps (which will be all identical):
+
+@example
+$ touch myfile
+
+$ lstime myfile
+Access (read): -rw-r--r-- 1 0 Dec 30 00:01 myfile
+Modify (data): -rw-r--r-- 1 0 Dec 30 00:01 myfile
+Change (meta): -rw-r--r-- 1 0 Dec 30 00:01 myfile
+
+$ stattime myfile
+File name:  myfile
+ Access (read): 2018-12-30 00:01:04.097305081 -0700
+ Modify (data): 2018-12-30 00:01:04.097305081 -0700
+ Change (meta): 2018-12-30 00:01:04.097305081 -0700
+@end example
+
+@iftex
+@exdent
+@end iftex
+Delay for 60 seconds, then change the file's permission mode.
+This is a meta-data change, hence @code{ctime} will be updated:
+
+@example
+$ sleep 60
+$ chmod g+w myfile
+
+$ lstime myfile
+Access (read): -rw-rw-r-- 1 0 Dec 30 00:01 myfile
+Modify (data): -rw-rw-r-- 1 0 Dec 30 00:01 myfile
+Change (meta): -rw-rw-r-- 1 0 Dec 30 00:02 myfile
+
+$ stattime myfile
+File name:  myfile
+ Access (read): 2018-12-30 00:01:04.097305081 -0700
+ Modify (data): 2018-12-30 00:01:04.097305081 -0700
+ Change (meta): 2018-12-30 00:02:09.735558316 -0700
+@end example
+
+@iftex
+@exdent
+@end iftex
+Delay for 120 seconds, then read the file.  This is a content read,
+hence @code{atime} will be updated:
+
+@example
+$ sleep 120
+$ cat myfile > /dev/null
+
+$ lstime myfile
+Access (read): -rw-rw-r-- 1 0 Dec 30 00:04 myfile
+Modify (data): -rw-rw-r-- 1 0 Dec 30 00:01 myfile
+Change (meta): -rw-rw-r-- 1 0 Dec 30 00:02 myfile
+
+$ stattime myfile
+File name:  myfile
+ Access (read): 2018-12-30 00:04:16.330307979 -0700
+ Modify (data): 2018-12-30 00:01:04.097305081 -0700
+ Change (meta): 2018-12-30 00:02:09.735558316 -0700
+@end example
+
+@iftex
+@exdent
+@end iftex
+Delay for 180 seconds, then append to the end of the file
+This is content modification, hence @code{mtime} and @code{ctime} will
+be updated (@code{stattime} omitted for brevity from now on):
+
+@example
+$ sleep 180
+$ echo a >> myfile
+
+$ lstime myfile
+Access (read): -rw-rw-r-- 1 2 Dec 30 00:04 myfile
+Modify (data): -rw-rw-r-- 1 2 Dec 30 00:07 myfile
+Change (meta): -rw-rw-r-- 1 2 Dec 30 00:07 myfile
+@end example
+
+@iftex
+@exdent
+@end iftex
+Delay for 240 seconds, then copy @file{myfile} to a new file
+(@file{otherfile}). The source file was read and its @code{atime} was
+updated. All timestamps of the destination file are set to the current
+time:
+
+@example
+$ sleep 240
+$ cp myfile otherfile
+
+$ lstime myfile
+Access (read): -rw-rw-r-- 1 2 Dec 30 00:11 myfile
+Modify (data): -rw-rw-r-- 1 2 Dec 30 00:07 myfile
+Change (meta): -rw-rw-r-- 1 2 Dec 30 00:07 myfile
+
+$ lstime otherfile
+Access (read): -rw-rw-r-- 1 2 Dec 30 00:11 myfile
+Modify (data): -rw-rw-r-- 1 2 Dec 30 00:11 myfile
+Change (meta): -rw-rw-r-- 1 2 Dec 30 00:11 myfile
+@end example
+
+@iftex
+@exdent
+@end iftex
+To copy the access time and modification time of the source file to
+the destination file, and prevent updating the access time of the
+source file, use @command{cp -p}.  The destination file's @code{ctime}
+will always be updated:
+
+@example
+$ sleep 60
+$ cp -p myfile thirdfile
+
+$ lstime myfile
+Access (read): -rw-rw-r-- 1 2 Dec 30 00:11 myfile
+Modify (data): -rw-rw-r-- 1 2 Dec 30 00:07 myfile
+Change (meta): -rw-rw-r-- 1 2 Dec 30 00:07 myfile
+
+$ lstime thirdfile
+Access (read): -rw-rw-r-- 1 2 Dec 30 00:11 thirdfile
+Modify (data): -rw-rw-r-- 1 2 Dec 30 00:07 thirdfile
+Change (meta): -rw-rw-r-- 1 2 Dec 30 00:12 thirdfile
+@end example
+
+
+
 @include parse-datetime.texi

-- 
2.11.0