@FILESTAMP
— returns
a file’s date and time stamps, in a consistent format and with correct
localization.
Syntax:
%@FILESTAMP[
filename,
flags,
fmt,
opt]
filename | the file to examine. It may not contain wildcards. Quote it if it contains spaces, commas, or other significant characters. |
flags | indicate which time stamp to return, and how to interpret it: |
W : returns the last-write (modification) time stamp; the default | |
C : returns the creation time stamp | |
A : returns the last-access stamp; see note below | |
L : returns the selected time stamp correctly localized; the default | |
U : returns the selected time stamp in UTC time, not localized | |
B : uses bad, broken, backward-compatible localization; see below | |
fmt | the date format used to return the date; defaults to 4, ISO 8601 format |
opt | set to 1 to use T as the date-time separator character, instead of an @ sign |
This function returns a file’s date and time stamps together, in one
call. The date and time will be separated by an @
sign.
@FILESTAMP
works like a combination of TCC’s internal
@FILEDATE
and @FILETIME
functions, but with some
differences that you should be aware of. The most important difference is
that this function correctly localizes time stamps of files on
NTFS volumes. It will return the same value for the same file, whether you
call it in May or in December. @FILETIME
, along with
DIR
and Explorer, can return different values for the same
file depending on when you examine it. Specifically, @FILETIME
et al. will return incorrect values if a timestamp on an NTFS
drive was set during Daylight Saving Time, but read during Standard Time,
or vice versa. In short, @FILESTAMP
may return different
times than @FILETIME
, DIR
, Explorer, and so on
for NTFS files — this is a deliberate feature and not a bug! If
you want localized file times to match DIR
and so on, specify
the B
flag, or just use @FILETIME
.
Since the date and time are read in one single operation, @FILESTAMP
is also immune to the possible errors that may occur if some other process
happens to access the target file between separate calls to @FILEDATE
and @FILETIME
.
The flags may be in any order. If you specify
incompatible flags, e.g. W
with C
or
L
with U
, the first one “wins”.
If you use the U
option, the time stamp will not be
localized (and will therefore agree with @FILETIME
given the
same option.) The returned time info will have the letter Z appended to
indicate UTC time.
File times will always be returned with seconds. There is no option to suppress the seconds.
The FAT filesystem, used on floppies and most flash sticks, records only
the date and not the time of the last access. If you specify the
A
flag for a file on a FAT drive, the last-access time will
always be returned as 00:00:00. If you specify both A
and
U
, the date will be returned as UTC, but the time will be
00:00:00Z. This behavior differs from TCC’s, but I think it’s the more
correct way of handling this situation.
Wildcards are not permitted in the filename.
This also differs from @FILEDATE
and @FILETIME
.
It would be easy enough to support wildcards, but if the filename contains
wildcards, then you may be getting info on a different file than you
thought you were checking; I prefer to require unambiguous
filenames here.
This function also supports a special output format which is not
supported elsewhere in this plugin. If fmt
is 276, then it will return a packed date and time without an @
sign, fourteen digits: YYYYMMDDhhmmss
. (276 is 20 plus 256.)
UTC timestamps will still include a Z
.
New in version 1.7.2: @FILESTAMP
supports internet files
beginning with ftp://
, http://
, or https://
.
For internet files, options W
, C
, and A
have no effect (there is only one time stamp to return), and times are always
localized unless you specify U
.
• New: This function does not exist in Take Command.