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 <assafgor...@gmail.com>
Date: Sun, 30 Dec 2018 20:28:28 -0700
Subject: [PATCH] doc: expand file timestamp section (atime,ctime,mtime)
Requested by kalle <ka...@projektwerkstatt.de> 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
