On 01/09/2017 10:32 AM, Scott Deerwester wrote: > This behavior should be > prominently documented in the man page for ls under the -u option.
Thanks for mentioning the issue. Although it's worth documenting I'm not sure it belongs in the ls man page, which is supposed to be quite terse. Instead, I documented it in the coreutils manual (which is the primary documentation for 'ls' anyway) by installing the attached. The first patch is a minor cleanup, the second the real doc change.
From 34562cb473a6d48d7f232d0154f5df08b6c8802e Mon Sep 17 00:00:00 2001 From: Paul Eggert <[email protected]> Date: Mon, 9 Jan 2017 12:12:02 -0800 Subject: [PATCH 1/2] maint: standardize on "timestamp" as per POSIX --- NEWS | 34 +++++++++++++++++----------------- doc/coreutils.texi | 36 ++++++++++++++++++------------------ src/copy.c | 8 ++++---- src/du.c | 8 ++++---- src/install.c | 2 +- src/ls.c | 12 ++++++------ src/touch.c | 4 ++-- tests/du/bigtime.sh | 6 +++--- tests/misc/ls-time.sh | 2 +- tests/misc/stat-nanoseconds.sh | 4 ++-- tests/misc/time-style.sh | 2 +- tests/touch/obsolescent.sh | 2 +- 12 files changed, 60 insertions(+), 60 deletions(-) diff --git a/NEWS b/NEWS index 9e0aaf4..1832d42 100644 --- a/NEWS +++ b/NEWS @@ -111,7 +111,7 @@ GNU coreutils NEWS -*- outline -*- seq no longer accepts 0 value as increment, and now also rejects NaN values for any argument. - stat now outputs nanosecond information for time stamps even if + stat now outputs nanosecond information for timestamps even if they are out of localtime range. sort, tail, and uniq now support traditional usage like 'sort +2' @@ -1492,7 +1492,7 @@ GNU coreutils NEWS -*- outline -*- ** Bug fixes cp -u no longer does unnecessary copying merely because the source - has finer-grained time stamps than the destination. + has finer-grained timestamps than the destination. od now prints floating-point numbers without losing information, and it no longer omits spaces between floating-point columns in some cases. @@ -1549,7 +1549,7 @@ GNU coreutils NEWS -*- outline -*- stat's %X, %Y, and %Z directives once again print only the integer part of seconds since the epoch. This reverts a change from coreutils-8.6, that was deemed unnecessarily disruptive. - To obtain a nanosecond-precision time stamp for %X use %.X; + To obtain a nanosecond-precision timestamp for %X use %.X; if you want (say) just 3 fractional digits, use %.3X. Likewise for %Y and %Z. @@ -1996,7 +1996,7 @@ GNU coreutils NEWS -*- outline -*- ** Bug fixes - cp, mv now ignore failure to preserve a symlink time stamp, when it is + cp, mv now ignore failure to preserve a symlink timestamp, when it is due to their running on a kernel older than what was implied by headers and libraries tested at configure time. [bug introduced in coreutils-7.5] @@ -2112,7 +2112,7 @@ GNU coreutils NEWS -*- outline -*- using copy-on-write (COW). This is currently only supported within a btrfs file system. - cp now preserves time stamps on symbolic links, when possible + cp now preserves timestamps on symbolic links, when possible sort accepts a new option, --human-numeric-sort (-h): sort numbers while honoring human readable suffixes like KiB and MB etc. @@ -3519,7 +3519,7 @@ GNU coreutils NEWS -*- outline -*- expr now detects integer overflow when converting strings to integers, rather than silently wrapping around. - ls now refuses to generate time stamps containing more than 1000 bytes, to + ls now refuses to generate timestamps containing more than 1000 bytes, to foil potential denial-of-service attacks on hosts with very large stacks. "mkdir -m =+x dir" no longer ignores the umask when evaluating "+x", @@ -3774,7 +3774,7 @@ GNU coreutils NEWS -*- outline -*- done reading it. This problem cannot occur unless '-m' is used. When outside the default POSIX locale, the 'who' and 'pinky' - commands now output time stamps like "2004-06-21 13:09" instead of + commands now output timestamps like "2004-06-21 13:09" instead of the traditional "Jun 21 13:09". pwd now works even when run from a working directory whose name @@ -3784,10 +3784,10 @@ GNU coreutils NEWS -*- outline -*- and -t is now a short name for their --target-directory option. cp -pu and mv -u (when copying) now don't bother to update the - destination if the resulting time stamp would be no newer than the - preexisting time stamp. This saves work in the common case when + destination if the resulting timestamp would be no newer than the + preexisting timestamp. This saves work in the common case when copying or moving multiple times to the same destination in a file - system with a coarse time stamp resolution. + system with a coarse timestamp resolution. cut accepts a new option, --complement, to complement the set of selected bytes, characters, or fields. @@ -3833,7 +3833,7 @@ GNU coreutils NEWS -*- outline -*- Dates like 'January 32' with out-of-range components are now rejected. - Dates can have fractional time stamps like 2004-02-27 14:19:13.489392193. + Dates can have fractional timestamps like 2004-02-27 14:19:13.489392193. Dates can be entered via integer counts of seconds since 1970 when prefixed by '@'. For example, '@321' represents 1970-01-01 00:05:21 UTC. @@ -3849,7 +3849,7 @@ GNU coreutils NEWS -*- outline -*- TZ="America/New_York" date --date='TZ="Europe/Paris" 2004-10-31 06:30' 'date' has a new option --iso-8601=ns that outputs - nanosecond-resolution time stamps. + nanosecond-resolution timestamps. echo -e '\xHH' now outputs a byte whose hexadecimal value is HH, for compatibility with bash. @@ -3956,7 +3956,7 @@ GNU coreutils NEWS -*- outline -*- 'cp -d' now works as required even on systems like OSF V5.1 that declare stat and lstat as 'static inline' functions. - time stamps output by stat now include actual fractional seconds, + timestamps output by stat now include actual fractional seconds, when available -- or .0000000 for files without that information. seq no longer infloops when printing 2^31 or more numbers. @@ -4514,14 +4514,14 @@ point at which the packages merged to form the coreutils: * ls -n now implies -l, as per POSIX. * ls can now display dates and times in one of four time styles: - - The 'full-iso' time style gives full ISO-style time stamps like + - The 'full-iso' time style gives full ISO-style timestamps like '2001-05-14 23:45:56.477817180 -0700'. - - The 'iso' time style gives ISO-style time stamps like '2001-05-14 ' + - The 'iso' time style gives ISO-style timestamps like '2001-05-14 ' and '05-14 23:45'. - - The 'locale' time style gives locale-dependent time stamps like + - The 'locale' time style gives locale-dependent timestamps like 'touko 14 2001' and 'touko 14 23:45' (in a Finnish locale). - The 'posix-iso' time style gives traditional POSIX-locale - time stamps like 'May 14 2001' and 'May 14 23:45' unless the user + timestamps like 'May 14 2001' and 'May 14 23:45' unless the user specifies a non-POSIX locale, in which case it uses ISO-style dates. This is the default. diff --git a/doc/coreutils.texi b/doc/coreutils.texi index c6febd4..dbb0a52 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -2474,7 +2474,7 @@ locale, the default is @samp{%b %e %H:%M %Y} (for example, @samp{Dec@ @ 4 23:59 2001}. @vindex TZ -Time stamps are listed according to the time zone rules specified by +Timestamps are listed according to the time zone rules specified by the @env{TZ} environment variable, or by the system default rules if @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ}, libc, The GNU C Library Reference Manual}. @@ -4671,7 +4671,7 @@ skipped. @item Sort a set of log files, primarily by IPv4 address and secondarily by -time stamp. If two lines' primary and secondary keys are identical, +timestamp. If two lines' primary and secondary keys are identical, output the lines in the same order that they were input. The log files contain lines that look like this: @@ -4692,8 +4692,8 @@ sort -s -t '.' -k 1,1n -k 2,2n -k 3,3n -k 4,4n This example cannot be done with a single @command{sort} invocation, since IPv4 address components are separated by @samp{.} while dates come just after a space. So it is broken down into two invocations of -@command{sort}: the first sorts by time stamp and the second by IPv4 -address. The time stamp is sorted by year, then month, then day, and +@command{sort}: the first sorts by timestamp and the second by IPv4 +address. The timestamp is sorted by year, then month, then day, and finally by hour-minute-second field, using @option{-k} to isolate each field. Except for hour-minute-second there's no need to specify the end of each key field, since the @samp{n} and @samp{M} modifiers sort @@ -7625,7 +7625,7 @@ which means you probably have clock skew problems which may break programs like @command{make} that rely on file timestamps. @vindex TZ -Time stamps are listed according to the time zone rules specified by +Timestamps are listed according to the time zone rules specified by the @env{TZ} environment variable, or by the system default rules if @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ}, libc, The GNU C Library Reference Manual}. @@ -8396,10 +8396,10 @@ results in an error message on systems that do not support symbolic links. @opindex --update @cindex newer files, copying only Do not copy a non-directory that has an existing destination with the -same or newer modification time. If time stamps are being preserved, -the comparison is to the source time stamp truncated to the +same or newer modification time. If timestamps are being preserved, +the comparison is to the source timestamp truncated to the resolutions of the destination file system and of the system calls -used to update time stamps; this avoids duplicate work if several +used to update timestamps; this avoids duplicate work if several @samp{cp -pu} commands are executed with the same source and destination. If @option{--preserve=links} is also specified (like with @samp{cp -au} for example), that will take precedence. Consequently, depending on the @@ -9258,8 +9258,8 @@ This option is mutually exclusive with @option{-b} or @option{--backup} option. Do not move a non-directory that has an existing destination with the same or newer modification time. If the move is across file system boundaries, the comparison is to the -source time stamp truncated to the resolutions of the destination file -system and of the system calls used to update time stamps; this avoids +source timestamp truncated to the resolutions of the destination file +system and of the system calls used to update timestamps; this avoids duplicate work if several @samp{mv -u} commands are executed with the same source and destination. @@ -10959,12 +10959,12 @@ birth time, when the file was first created; by definition, this timestamp never changes. @vindex TZ -Time stamps assume the time zone rules specified by the @env{TZ} +Timestamps assume the time zone rules specified by the @env{TZ} environment variable, or by the system default rules if @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ}, libc, The GNU C Library Reference Manual}. You can avoid ambiguities during -daylight saving transitions by using UTC time stamps. +daylight saving transitions by using UTC timestamps. The program accepts the following options. Also see @ref{Common options}. @@ -10998,7 +10998,7 @@ example, @option{--date="2004-02-27 14:19:13.489392193 +0530"} specifies the instant of time that is 489,392,193 nanoseconds after February 27, 2004 at 2:19:13 PM in a time zone that is 5 hours and 30 minutes east of UTC@. @xref{Date input formats}. -File systems that do not support high-resolution time stamps +File systems that do not support high-resolution timestamps silently ignore any excess precision here. @item -f @@ -11041,8 +11041,8 @@ Use the times of the reference @var{file} instead of the current time. If this option is combined with the @option{--date=@var{time}} (@option{-d @var{time}}) option, the reference @var{file}'s time is the origin for any relative @var{time}s given, but is otherwise ignored. -For example, @samp{-r foo -d '-5 seconds'} specifies a time stamp -equal to five seconds before the corresponding time stamp for @file{foo}. +For example, @samp{-r foo -d '-5 seconds'} specifies a timestamp +equal to five seconds before the corresponding timestamp for @file{foo}. If @var{file} is a symbolic link, the reference timestamp is taken from the target of the symlink, unless @option{-h} was also in effect. @@ -11880,7 +11880,7 @@ precision preceded by a period to specify the number of digits to print after the decimal point. For example, @samp{%.3X} outputs the last access time to millisecond precision. If a period is given but no precision, @command{stat} uses 9 digits, so @samp{%.X} is equivalent to -@samp{%.9X}@. When discarding excess precision, time stamps are truncated +@samp{%.9X}@. When discarding excess precision, timestamps are truncated toward minus infinity. @example @@ -11935,7 +11935,7 @@ you must use a different set of @var{format} directives: @end itemize @vindex TZ -Time stamps are listed according to the time zone rules specified by +Timestamps are listed according to the time zone rules specified by the @env{TZ} environment variable, or by the system default rules if @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ}, libc, The GNU C Library Reference Manual}. @@ -14944,7 +14944,7 @@ by the hostname. Traditionally, the two arguments given are @samp{am i}, as in @samp{who am i}. @vindex TZ -Time stamps are listed according to the time zone rules specified by +Timestamps are listed according to the time zone rules specified by the @env{TZ} environment variable, or by the system default rules if @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ}, libc, The GNU C Library Reference Manual}. diff --git a/src/copy.c b/src/copy.c index 38d7c5d..c3d71cb 100644 --- a/src/copy.c +++ b/src/copy.c @@ -1946,9 +1946,9 @@ copy_internal (char const *src_name, char const *dst_name, if (!S_ISDIR (src_mode) && x->update) { - /* When preserving time stamps (but not moving within a file - system), don't worry if the destination time stamp is - less than the source merely because of time stamp + /* When preserving timestamps (but not moving within a file + system), don't worry if the destination timestamp is + less than the source merely because of timestamp truncation. */ int options = ((x->preserve_timestamps && ! (x->move_mode @@ -2681,7 +2681,7 @@ copy_internal (char const *src_name, char const *dst_name, /* See if the destination is already the desired symlink. FIXME: This behavior isn't documented, and seems wrong in some cases, e.g., if the destination symlink has the - wrong ownership, permissions, or time stamps. */ + wrong ownership, permissions, or timestamps. */ char *dest_link_val = areadlink_with_size (dst_name, dst_sb.st_size); if (dest_link_val && STREQ (dest_link_val, src_link_val)) diff --git a/src/du.c b/src/du.c index fa35569..8e88b56 100644 --- a/src/du.c +++ b/src/du.c @@ -81,8 +81,8 @@ struct duinfo /* Number of inodes in directory. */ uintmax_t inodes; - /* Latest time stamp found. If tmax.tv_sec == TYPE_MINIMUM (time_t) - && tmax.tv_nsec < 0, no time stamp has been found. */ + /* Latest timestamp found. If tmax.tv_sec == TYPE_MINIMUM (time_t) + && tmax.tv_nsec < 0, no timestamp has been found. */ struct timespec tmax; }; @@ -255,8 +255,8 @@ static enum time_type const time_types[] = ARGMATCH_VERIFY (time_args, time_types); /* 'full-iso' uses full ISO-style dates and times. 'long-iso' uses longer - ISO-style time stamps, though shorter than 'full-iso'. 'iso' uses shorter - ISO-style time stamps. */ + ISO-style timestamps, though shorter than 'full-iso'. 'iso' uses shorter + ISO-style timestamps. */ enum time_style { full_iso_time_style, /* --time-style=full-iso */ diff --git a/src/install.c b/src/install.c index 33496bd..592c345 100644 --- a/src/install.c +++ b/src/install.c @@ -531,7 +531,7 @@ change_timestamps (struct stat const *src_sb, char const *dest) if (utimens (dest, timespec)) { - error (0, errno, _("cannot set time stamps for %s"), quoteaf (dest)); + error (0, errno, _("cannot set timestamps for %s"), quoteaf (dest)); return false; } return true; diff --git a/src/ls.c b/src/ls.c index 53c074f..556313c 100644 --- a/src/ls.c +++ b/src/ls.c @@ -418,8 +418,8 @@ enum format static enum format format; /* 'full-iso' uses full ISO-style dates and times. 'long-iso' uses longer - ISO-style time stamps, though shorter than 'full-iso'. 'iso' uses shorter - ISO-style time stamps. 'locale' uses locale-dependent time stamps. */ + ISO-style timestamps, though shorter than 'full-iso'. 'iso' uses shorter + ISO-style timestamps. 'locale' uses locale-dependent timestamps. */ enum time_style { full_iso_time_style, /* --time-style=full-iso */ @@ -730,11 +730,11 @@ static bool format_needs_stat; static bool format_needs_type; -/* An arbitrary limit on the number of bytes in a printed time stamp. +/* An arbitrary limit on the number of bytes in a printed timestamp. This is set to a relatively small value to avoid the need to worry about denial-of-service attacks on servers that run "ls" on behalf of remote clients. 1000 bytes should be enough for any practical - time stamp format. */ + timestamp format. */ enum { TIME_STAMP_LEN_MAXIMUM = MAX (1000, INT_STRLEN_BOUND (time_t)) }; @@ -1079,7 +1079,7 @@ first_percent_b (char const *fmt) /* max number of display cells to use */ enum { MAX_MON_WIDTH = 5 }; -/* abformat[RECENT][MON] is the format to use for time stamps with +/* abformat[RECENT][MON] is the format to use for timestamps with recentness RECENT and month MON. */ enum { ABFORMAT_SIZE = 128 }; static char abformat[2][12][ABFORMAT_SIZE]; @@ -3813,7 +3813,7 @@ align_nstrftime (char *buf, size_t size, bool recent, struct tm const *tm, return nstrftime (buf, size, nfmt, tm, tz, ns); } -/* Return the expected number of columns in a long-format time stamp, +/* Return the expected number of columns in a long-format timestamp, or zero if it cannot be calculated. */ static int diff --git a/src/touch.c b/src/touch.c index ff0ba92..cd4a9d3 100644 --- a/src/touch.c +++ b/src/touch.c @@ -374,8 +374,8 @@ main (int argc, char **argv) && newtime[0].tv_sec == now.tv_sec && newtime[0].tv_nsec == now.tv_nsec) { - /* Check that it really was "-d now", and not a time - stamp that just happens to be the current time. */ + /* Check that it really was "-d now", and not a timestamp + that just happens to be the current time. */ struct timespec notnow, notnow1; notnow.tv_sec = now.tv_sec ^ 1; notnow.tv_nsec = now.tv_nsec; diff --git a/tests/du/bigtime.sh b/tests/du/bigtime.sh index 15f8cbd..14bd036 100755 --- a/tests/du/bigtime.sh +++ b/tests/du/bigtime.sh @@ -1,5 +1,5 @@ #!/bin/sh -# Exercise du on a file with a big time stamp. +# Exercise du on a file with a big timestamp. # Copyright (C) 2010-2017 Free Software Foundation, Inc. @@ -33,9 +33,9 @@ case "$future_time" in *' Dec 4 300627798676 '*) skip_ "file system and localtime both handle big timestamps" ;; *) - skip_ "file system or localtime mishandles big time stamps:" \ + skip_ "file system or localtime mishandles big timestamps:" \ "$future_time" ;; -esac || skip_ "file system cannot represent big time stamps" +esac || skip_ "file system cannot represent big timestamps" printf "0\t$bignum\tfuture\n" > exp || framework_failure_ printf "du: time '$bignum' is out of range\n" > err_ok || framework_failure_ diff --git a/tests/misc/ls-time.sh b/tests/misc/ls-time.sh index 8b56dd5..d42eb24 100755 --- a/tests/misc/ls-time.sh +++ b/tests/misc/ls-time.sh @@ -20,7 +20,7 @@ print_ver_ ls # Avoid any possible glitches due to daylight-saving changes near the -# time stamps used during the test. +# timestamps used during the test. TZ=UTC0 export TZ diff --git a/tests/misc/stat-nanoseconds.sh b/tests/misc/stat-nanoseconds.sh index 8af215c..d2b07c7 100755 --- a/tests/misc/stat-nanoseconds.sh +++ b/tests/misc/stat-nanoseconds.sh @@ -23,11 +23,11 @@ print_ver_ stat TZ=UTC0 export TZ -# Use a time stamp near the Epoch to avoid trouble with leap seconds. +# Use a timestamp near the Epoch to avoid trouble with leap seconds. touch -d '1970-01-01 18:43:33.023456789' k || framework_failure_ ls --full-time | grep 18:43:33.023456789 \ - || skip_ this file system does not support sub-second time stamps + || skip_ this file system does not support sub-second timestamps test "$(stat -c %X k)" = 67413 || fail=1 test "$(stat -c %.X k)" = 67413.023456789 || fail=1 diff --git a/tests/misc/time-style.sh b/tests/misc/time-style.sh index 2383be3..ec1d4ab 100755 --- a/tests/misc/time-style.sh +++ b/tests/misc/time-style.sh @@ -23,7 +23,7 @@ print_ver_ pr echo hello >a || framework_failure_ -# The tests assume this is an old time stamp in northern hemisphere summer. +# The tests assume this is an old timestamp in northern hemisphere summer. TZ=UTC0 touch -d '1970-07-08 09:10:11' a || framework_failure_ for tz in UTC0 PST8 PST8PDT,M3.2.0,M11.1.0 XXXYYY-12:30; do diff --git a/tests/touch/obsolescent.sh b/tests/touch/obsolescent.sh index f52e839..96d730f 100755 --- a/tests/touch/obsolescent.sh +++ b/tests/touch/obsolescent.sh @@ -1,5 +1,5 @@ #!/bin/sh -# Test touch with obsolescent 8- or 10-digit time stamps. +# Test touch with obsolescent 8- or 10-digit timestamps. # Copyright (C) 2000-2017 Free Software Foundation, Inc. -- 2.9.3
From 13b66dd9efc85842241c38769e0f75a7a3306b2f Mon Sep 17 00:00:00 2001 From: Paul Eggert <[email protected]> Date: Mon, 9 Jan 2017 15:14:09 -0800 Subject: [PATCH 2/2] doc: cover file timestamps better Prompted by a bug report from Scott Deerwester (Bug#25407). * doc/coreutils.texi (File timestamps): New section. Revamp other sections to use this new section, and use more-consistent terminology. --- doc/coreutils.texi | 175 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 107 insertions(+), 68 deletions(-) diff --git a/doc/coreutils.texi b/doc/coreutils.texi index dbb0a52..1b4a931 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -342,6 +342,7 @@ Changing file attributes * chgrp invocation:: Change group ownership * chmod invocation:: Change access permissions * touch invocation:: Change file timestamps +* File timestamps:: File timestamp issues Disk usage @@ -7121,7 +7122,8 @@ uniquely identifies each file within a particular file system.) In addition to the name of each file, print the file type, file mode bits, number of hard links, owner name, group name, size, and timestamp (@pxref{Formatting file timestamps}), normally -the modification time. Print question marks for information that +the modification timestamp (the mtime, @pxref{File timestamps}). +Print question marks for information that cannot be determined. Normally the size is printed as a byte count without punctuation, but @@ -7292,11 +7294,10 @@ it outputs. By default, sorting is done by character code @opindex status time@r{, printing or sorting by} @opindex use time@r{, printing or sorting files by} If the long listing format (e.g., @option{-l}, @option{-o}) is being used, -print the status change time (the @samp{ctime} in the inode) instead of -the modification time. +print the status change timestamp (the ctime) instead of the mtime. When explicitly sorting by time (@option{--sort=time} or @option{-t}) or when not using a long listing format, -sort according to the status change time. +sort according to the ctime. @xref{File timestamps}. @item -f @opindex -f @@ -7326,8 +7327,9 @@ Sort by file size, largest first. @itemx --sort=time @opindex -t @opindex --sort -@opindex modification time@r{, sorting files by} -Sort by modification time (the @samp{mtime} in the inode), newest first. +@opindex modification timestamp@r{, sorting files by} +Sort by modification timestamp (mtime), newest first. +@xref{File timestamps}. @item -u @itemx --time=atime @@ -7337,11 +7339,12 @@ Sort by modification time (the @samp{mtime} in the inode), newest first. @opindex --time @opindex use time@r{, printing or sorting files by} @opindex atime@r{, printing or sorting files by} -@opindex access time@r{, printing or sorting files by} +@opindex access timestamp@r{, printing or sorting files by} If the long listing format (e.g., @option{--format=long}) is being used, -print the last access time (the @samp{atime} in the inode). +print the last access timestamp (the atime). When explicitly sorting by time (@option{--sort=time} or @option{-t}) -or when not using a long listing format, sort according to the access time. +or when not using a long listing format, sort according to the atime. +@xref{File timestamps}. @item -U @itemx --sort=none @@ -7623,6 +7626,7 @@ months old, and is not dated in the future. If a timestamp dated today is not listed in recent form, the timestamp is in the future, which means you probably have clock skew problems which may break programs like @command{make} that rely on file timestamps. +@xref{File timestamps}. @vindex TZ Timestamps are listed according to the time zone rules specified by @@ -8396,7 +8400,7 @@ results in an error message on systems that do not support symbolic links. @opindex --update @cindex newer files, copying only Do not copy a non-directory that has an existing destination with the -same or newer modification time. If timestamps are being preserved, +same or newer modification timestamp. If timestamps are being preserved, the comparison is to the source timestamp truncated to the resolutions of the destination file system and of the system calls used to update timestamps; this avoids duplicate work if several @@ -8795,8 +8799,9 @@ Use non-blocking I/O. @item noatime @opindex noatime -@cindex access time -Do not update the file's access time. +@cindex access timestamp +Do not update the file's access timestamp. +@xref{File timestamps}. Some older file systems silently ignore this flag, so it is a good idea to test it on your files before relying on it. @@ -9108,8 +9113,8 @@ print a warning and ignore the option. Set the time of last access and the time of last modification of each installed file to match those of each corresponding original file. When a file is installed without this option, its last access and -last modification times are both set to the time of installation. -This option is useful if you want to use the last modification times +last modification timestamps are both set to the time of installation. +This option is useful if you want to use the last modification timestamps of installed files to keep track of when they were last built as opposed to when they were last installed. @@ -9256,7 +9261,7 @@ This option is mutually exclusive with @option{-b} or @option{--backup} option. @opindex --update @cindex newer files, moving only Do not move a non-directory that has an existing destination with the -same or newer modification time. +same or newer modification timestamp. If the move is across file system boundaries, the comparison is to the source timestamp truncated to the resolutions of the destination file system and of the system calls used to update timestamps; this avoids @@ -10427,6 +10432,7 @@ These commands change file attributes. * chgrp invocation:: Change file groups. * chmod invocation:: Change access permissions. * touch invocation:: Change file timestamps. +* File timestamps:: File timestamp issues. @end menu @@ -10889,7 +10895,7 @@ Recursively change permissions of directories and their contents. @cindex file timestamps, changing @cindex timestamps, changing file -@command{touch} changes the access and/or modification times of the +@command{touch} changes the access and/or modification timestamps of the specified files. Synopsis: @example @@ -10905,58 +10911,24 @@ A @var{file} argument string of @samp{-} is handled specially and causes @command{touch} to change the times of the file associated with standard output. -@cindex clock skew By default, @command{touch} sets file timestamps to the current time. Because @command{touch} acts on its operands left to right, the resulting timestamps of earlier and later operands may disagree. -Also, the determination of what time is ``current'' depends on the -platform. Platforms with network file systems often use different -clocks for the operating system and for file systems; because -@command{touch} typically uses file systems' clocks by default, clock -skew can cause the resulting file timestamps to appear to be in a -program's ``future'' or ``past''. - -@cindex file timestamp resolution -The @command{touch} command sets the file's timestamp to the greatest -representable value that is not greater than the requested time. This -can differ from the requested time for several reasons. First, the -requested time may have a higher resolution than supported. Second, a -file system may use different resolutions for different types of -times. Third, file timestamps may use a different resolution than -operating system timestamps. Fourth, the operating system primitives -used to update timestamps may employ yet a different resolution. For -example, in theory a file system might use 10-microsecond resolution -for access time and 100-nanosecond resolution for modification time, -and the operating system might use nanosecond resolution for the -current time and microsecond resolution for the primitive that -@command{touch} uses to set a file's timestamp to an arbitrary value. @cindex permissions, for changing file timestamps When setting file timestamps to the current time, @command{touch} can change the timestamps for files that the user does not own but has write permission for. Otherwise, the user must own the files. Some older systems have a further restriction: the user must own the files -unless both the access and modification times are being set to the +unless both the access and modification timestamps are being set to the current time. -Although @command{touch} provides options for changing two of the times---the -times of last access and modification---of a file, there is actually -a standard third one as well: the inode change time. This is often -referred to as a file's @code{ctime}. -The inode change time represents the time when the file's meta-information -last changed. One common example of this is when the permissions of a -file change. Changing the permissions doesn't access the file, so -the atime doesn't change, nor does it modify the file, so the mtime -doesn't change. Yet, something about the file itself has changed, -and this must be noted somewhere. This is the job of the ctime field. -This is necessary, so that, for example, a backup program can make a -fresh copy of the file, including the new permissions value. -Another operation that modifies a file's ctime without affecting -the others is renaming. In any case, it is not possible, in normal -operations, for a user to change the ctime field to a user-specified value. -Some operating systems and file systems support a fourth time: the -birth time, when the file was first created; by definition, this -timestamp never changes. +The @command{touch} command cannot set a file's status change timestamp to +a user-specified value, and cannot change the file's birth time (if +supported) at all. Also, @command{touch} has issues similar to those +affecting all programs that update file timestamps. For example, +@command{touch} may set a file's timestamp to a value that differs +slightly from the requested time. @xref{File timestamps}. @vindex TZ Timestamps assume the time zone rules specified by the @env{TZ} @@ -10979,7 +10951,7 @@ The program accepts the following options. Also see @ref{Common options}. @opindex atime@r{, changing} @opindex access @r{time, changing} @opindex use @r{time, changing} -Change the access time only. +Change the access timestamp only. @xref{File timestamps}. @item -c @itemx --no-create @@ -11019,7 +10991,7 @@ about files that do not exist. Not all systems support changing the timestamps of symlinks, since underlying system support for this action was not required until POSIX 2008. Also, on some systems, the mere act of examining a symbolic link changes the access -time, such that only changes to the modification time will persist +timestamp, such that only changes to the modification timestamp will persist long enough to be observable. When coupled with option @option{-r}, a reference timestamp is taken from a symbolic link rather than the file it refers to. @@ -11031,7 +11003,7 @@ it refers to. @opindex --time @opindex mtime@r{, changing} @opindex modify @r{time, changing} -Change the modification time only. +Change the modification timestamp only. @item -r @var{file} @itemx --reference=@var{file} @@ -11079,6 +11051,73 @@ For example, use @samp{touch ./12312359 main.c} or @samp{touch -t @exitstatus +@node File timestamps +@section File timestamps + +@cindex atime +@cindex birthtime +@cindex ctime +@cindex mtime +Standard POSIX files have three timestamps: the access timestamp +(atime) of the last read, the modification timestamp (mtime) of the +last write, and the status change timestamp (ctime) of the last change +to the the file's meta-information. Some file systems support a +fourth time: the birth timestamp (birthtime) of when the file was +created; by definition, birthtime never changes. + +One common example of a ctime change is when the permissions of a file +change. Changing the permissions doesn't access the file, so atime +doesn't change, nor does it modify the file, so the mtime doesn't +change. Yet, something about the file itself has changed, and this +must be noted somewhere. This is the job of the ctime field. This is +necessary, so that, for example, a backup program can make a fresh +copy of the file, including the new permissions value. Another +operation that modifies a file's ctime without affecting the others is +renaming. + +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 +file's atime and mtime can also be set directly, via the +@command{touch} command (@pxref{touch invocation}). In practice, +though, timestamps are not updated quite that way. + +For efficiency reasons, many systems are lazy about updating atimes: +when a program accesses a file, they may delay updating the file's +atime, or may not update the file's atime if the file has been +accessed recently, or may not update the atime at all. Similar +laziness, though typically not quite so extreme, applies to mtimes and +ctimes. + +Some systems emulate timestamps instead of supporting them directly, +and these emulations may disagree with the naive interpretation. For +example, a system may fake an atime or ctime by using the mtime. + +@cindex clock skew +The determination of what time is ``current'' depends on the +platform. Platforms with network file systems often use different +clocks for the operating system and for file systems; because +updates typically uses file systems' clocks by default, clock +skew can cause the resulting file timestamps to appear to be in a +program's ``future'' or ``past''. + +@cindex file timestamp resolution +When the system updates a file timestamp to a desired time @var{t} +(which is either the current time, or a time specified via the +@command{touch} command), there are several reasons the file's +timestamp may be set to a value that differs from @var{t}. First, +@var{t} may have a higher resolution than supported. Second, a file +system may use different resolutions for different types of times. +Third, file timestamps may use a different resolution than operating +system timestamps. Fourth, the operating system primitives used to +update timestamps may employ yet a different resolution. For example, +in theory a file system might use 10-microsecond resolution for access +timestamp and 100-nanosecond resolution for modification timestamp, and the +operating system might use nanosecond resolution for the current time +and microsecond resolution for the primitive that @command{touch} uses +to set a file's timestamp to an arbitrary value. + + @node Disk usage @chapter Disk usage @@ -11630,8 +11669,8 @@ du --inodes -x --threshold=20000 / @item --time @opindex --time @cindex last modified dates, displaying in @command{du} -Show time of the most recent modification of any file in the directory, -or any of its subdirectories. +Show the most recent modification timestamp (mtime) of any file in the +directory, or any of its subdirectories. @xref{File timestamps}. @item --time=ctime @itemx --time=status @@ -11640,16 +11679,16 @@ or any of its subdirectories. @opindex ctime@r{, show the most recent} @opindex status time@r{, show the most recent} @opindex use time@r{, show the most recent} -Show the most recent status change time (the @samp{ctime} in the inode) of -any file in the directory, instead of the modification time. +Show the most recent status change timestamp (ctime) of any file in +the directory, or any of its subdirectories. @xref{File timestamps}. @item --time=atime @itemx --time=access @opindex --time @opindex atime@r{, show the most recent} -@opindex access time@r{, show the most recent} -Show the most recent access time (the @samp{atime} in the inode) of -any file in the directory, instead of the modification time. +@opindex access timestamp@r{, show the most recent} +Show the most recent access timestamp (atime) of any file in the +directory, or any of its subdirectories. @xref{File timestamps}. @item --time-style=@var{style} @opindex --time-style @@ -11878,7 +11917,7 @@ represent other quantities. The @samp{%W}, @samp{%X}, @samp{%Y}, and @samp{%Z} formats accept a precision preceded by a period to specify the number of digits to print after the decimal point. For example, @samp{%.3X} outputs the -last access time to millisecond precision. If a period is given but no +access timestamp to millisecond precision. If a period is given but no precision, @command{stat} uses 9 digits, so @samp{%.X} is equivalent to @samp{%.9X}@. When discarding excess precision, timestamps are truncated toward minus infinity. -- 2.9.3
