<stat [options] $path[ /]> [</stat>]
stat function obtains information about file(s). It
combines functionality from the Unix utilities
find. For each file named in the
$path argument (plus others, depending on options below), the
following variables are set in parallel:
The file path. This is usually a value from the
argument, but if
MAXDEPTH is set, new
paths may be returned.
The error from
stat() for this file, or empty if no error.
Thus, if the file named by
$path does not exist,
$ret.err will be non-empty. Note that it is possible for
errors to occur on files not specified in the original
$path list, if
MAXDEPTH is set. If
$ret.err is non-empty, any variables derived from a
stat() call (e.g.
$ret.size) will also be unset,
empty or 0.
The number of directories traversed from an original
argument to this file, excluding any initial filename globbing.
Top-level paths will thus have a depth of 0.
The raw target of the symlink. For non-symlink files and
platforms that do not support symbolic links, this is empty.
The target of a symlink, as a corrected path from the top-level
$path argument. For non-symlink files and platforms that
do not support symbolic links, this is empty.
The size of the file, in bytes. On systems where filesizes can
exceed the size of a
long (e.g. Solaris 2.6/2.7/2.8), the
value is returned as an
int64 (version 5 and earlier
The owner of the file.
The group of the file.
1 if the file is readable with current permissions, 0 if not.
1 if the file is writable with current permissions, 0 if not.
1 if the file is executable with current permissions, 0 if not.
Type and permissions of the file, as a 10-character symbolic
string ala Unix
ls. The first character denotes the type
of file: "
d" for a directory, "
-" for a regular
b" for a block device, "
c" for a
character device, "
p" for a FIFO or pipe, "
for a symlink, "
s" for a socket. The next 3 characters
w" and "
x" respectively, to
indicate read, write and execute permission for the file owner, or
-" to indicate the permission is not given.
Under Unix, the next 3 characters are the same, for the group.
The last three are the same, for others. The user execute bit may
s" if the set-uid bit is also set, or "
the set-uid bit is set without execute. The group execute bit may
s" if the set-gid bit is also set, or "
the set-gid bit is set without execute. The other execute bit may
t" if the save-text (sticky) bit is also set, or
T" if the bit is set without execute.
List of file attributes of the file, as a comma-separated list of
zero or more of the following tokens:
encrypted. This is a Windows-specific return value: on
$ret.attrib may be emulated to a limited extent
(e.g. under Unix
readonly is set if the file is not writable),
$ret.mode contains more details.
Added in version 5.01.1245200000 20090616.
The last-access time of the file, which is generally the last time
a process read from the file.
The last-modify time of the file.
The last-change time of the file, i.e. the last time its attributes
The number of hard links to the files (if the filesystem/platform
The device type the file is on (if the filesystem/platform supports it).
Under Unix, the device major and minor number (combined). Under
Windows, this usually indicates what drive the file is on: 0 for
A:, 1 for B:, etc. (For UNC paths this may be the drive that the
process is on, not the file; this is apparently a limitation of
The inode of the file (if the filesystem/platform supports it).
The number of blocks consumed by the file, if the filesystem/platform
The preferred block size for file transfers on the device, if the
filesystem/platform supports it.
</stat> tag is optional: if present, the function
becomes a looping block statement, with the return variables looped
over and any statements inside the block executed for each iteration;
$next are also set then.
(here) may be used to exit the loop.
The following options may be set before the
stat returns the file path in
$ret, plus various other
$ret.... variables as listed above. If the looping syntax is
used (a closing
are set as well as the other variables.
<IF $ret.err neq "">
The file does not exist! ($ret.err)
Contents of directory $dir:
<stat ROW MAXDEPTH=1 SKIP=1 ALL $dir>
<fmt "%s %8s %8s %10kd %at %s\n"
$ret.mode $ret.owner $ret.group
$ret.size "%b %d %Y" $ret.mtime $ret>
The top part of this example checks for the existence of a file, and
reports if it cannot be found. The bottom part of the example
dir of the directory
prints out some information on the files contained therein: setting
MAXDEPTH to 1 ensures the directory contents are returned as well,
SKIP=1 skips the directory name itself, and
." and "
.." are returned too.
stat function was added in version 3.01.982000000 20010212.
Certain return variables are platform-dependent, such as
FOLLOWSYM option can cause repetitive, copious and
useless return values if symbolic links point to directories, as
the resulting filesystem loop will be followed.
Copyright © Thunderstone Software Last updated: Mon Feb 18 10:28:15 EST 2013