stat - obtain file size and attributes

`stat` - obtain file size and attributes

SYNOPSIS

<stat [options] $path[ /]> [</stat>]

DESCRIPTION
The stat function obtains information about file(s). It combines functionality from the Unix utilities ls, stat() and find. For each file named in the $path argument (plus others, depending on options below), the following variables are set in parallel:

$ret (string) The file path. This is usually a value from the $path argument, but if GLOB or MAXDEPTH is set, new paths may be returned.
$ret.err (string) 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 GLOB or 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.
$ret.depth (long) The number of directories traversed from an original $path argument to this file, excluding any initial filename globbing. Top-level paths will thus have a depth of 0.
$ret.symlink (string) The raw target of the symlink. For non-symlink files and platforms that do not support symbolic links, this is empty.
$ret.sympath (string) 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.
$ret.size (int64) The size of the file, in bytes. In version 6 and earlier, on various platforms this may be long or double instead.
$ret.ownerid (string)
In syntaxversion 8 and later, the integer UID (if Unix) or string SID (if Windows) of the owner of the file.
$ret.owner (string)
The name of the owner of the file. Under Windows this includes the domain name, in Texis version 8 and later. Empty if RESOLVEUSERNAMES is not given (default in syntaxversion 8 and later, to save time/resources), or if name cannot be resolved. In syntaxversion 7 and earlier under Unix, this may be the string UID if name cannot be resolved. (See $ret.ownerid for reliable UID.)
$ret.groupid (string)
In syntaxversion 8 and later, the integer GID (if Unix) or string SID (if Windows) of the group of the file.
$ret.group (string)
The name of the group of the file. Under Windows this includes the domain name, in Texis version 8 and later. Empty if RESOLVEUSERNAMES is not given (default in syntaxversion 8 and later, to save time/resources), or if name cannot be resolved. In syntaxversion 7 and earlier under Unix, this may be the string GID if name cannot be resolved. (See $ret.groupid for reliable GID.)
$ret.isrd (long) 1 if the file is readable with current permissions, 0 if not.
$ret.iswr (long) 1 if the file is writable with current permissions, 0 if not.
$ret.isex (long) 1 if the file is executable with current permissions, 0 if not.
$ret.mode (string) 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 file, "b" for a block device, "c" for a character device, "p" for a FIFO or pipe, "l" for a symlink, "s" for a socket. The next 3 characters are "r", "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 be "s" if the set-uid bit is also set, or "S" if the set-uid bit is set without execute. The group execute bit may be "s" if the set-gid bit is also set, or "S" if the set-gid bit is set without execute. The other execute bit may be "t" if the save-text (sticky) bit is also set, or "T" if the bit is set without execute.
$ret.attrib (string) List of file attributes of the file, as a comma-separated list of zero or more of the following tokens: readonly, hidden, system, volumelabel, directory, archive, device, normal, temporary, sparsefile, reparsepoint, compressed, offline, notcontentindexed, encrypted. This is a Windows-specific return value: on other OSes, $ret.attrib may be emulated to a limited extent (e.g. under Unix readonly is set if the file is not writable), and $ret.mode contains more details. Added in version 5.01.1245200000 20090616.
$ret.atime (date) The last-access time of the file, which is generally the last time a process read from the file.
$ret.mtime (date) The last-modify time of the file.
$ret.ctime (date) The last-change time of the file, i.e. the last time its attributes were changed.
$ret.nlinks (long) The number of hard links to the files (if the filesystem/platform supports it).
$ret.devtype (long) The device type the file is on (if the filesystem/platform supports it).
$ret.dev (long) 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 Windows stat() implementation.)
$ret.ino (long) The inode of the file (if the filesystem/platform supports it).
$ret.blks (long) The number of blocks consumed by the file, if the filesystem/platform supports it.
$ret.blksize (long) The preferred block size for file transfers on the device, if the filesystem/platform supports it.

In version 8 syntax - i.e. when the syntaxversion pragma (here) is 8 or more, the default in version 8 - stat is non-looping if self-closed, looping otherwise (requiring a close tag), like other loopable statements. Also, RESOLVEUSERNAMES is off by default.

In version 7 and earlier syntax, the statement is non-looping if self-closed or there is no matching close tag, looping otherwise; and RESOLVEUSERNAMES is implicitly on.

When looping, the return variables are looped over and any statements inside the block are executed for each iteration; $loop and $next are also set. <BREAK> (here) may be used to exit the loop. $loop and $next are also set in version 8.00.1645136290 20220217 and later when the statement is self-closing. Note that in version 8 and later syntax, the return variables do not accumulate when looping.

The following options may be set before the $path argument:

ROW
Note that in version 8 and later syntax - i.e. when the syntaxversion pragma (here) is 8 or more - return values never accumulate in looping statements. Thus the ROW flag is unneeded, and not accepted. It is only valid in version 7 and earlier syntax.
In version 7 and earlier syntax, the ROW flag indicates that return variables should not accumulate into arrays, nor be entered into loop contexts; each iteration's values will replace the previous. This option is recommended if the return values are not needed in future iterations; it saves memory.
SKIP=n Skip the first n return values. For example, to list just the contents of a single directory, SKIP=1 with MAXDEPTH=1 will skip the initial value (the directory itself).
MAX=n Return at most n values, after SKIP, globbing and recursion if any.
MAXDEPTH=n Descend at most n directories deep from the top-level $path argument values (after globbing). The default is 0, i.e. do not descend directories. A negative value indicates no limit.
NAME=wildcard Only return files whose name (not path) matches the wildcard specification. Similar to the -name option to the Unix find utility.
ALL Return all entries from a traversed directory; do not skip "." and "..".
SAMEDEV Stay on the same device as the current $path argument; do not cross filesystems when traversing directories if MAXDEPTH specified. Same as the -xdev or -mount option to the Unix find utility. May not work correctly under Windows.
DEPTHFIRST When traversing directories (if MAXDEPTH set), return a directory's contents before the directory name itself. The default is to return the directory name before returning its contents.
SYMLINK Return information about symlinks, not the files they point to; i.e. use lstat() instead of stat(). This does not affect the value of $ret.symlink or $ret.sympath, nor the traversal of directories (see FOLLOWSYM option); it will affect other stat()-dependent variables such as $ret.mode however.
FOLLOWSYM Follow symbolic links that point to directories when traversing for MAXDEPTH; the default is not to. Note: this can cause the same directory tree to be traversed many times, e.g. if a symbolic link points to an upper-level directory.
GLOB Do shell-style file globbing: expand wildcards ("*" and "?") in the original $path argument's values, and return values for the resulting paths. The expanded values for a given $path wildcard are sorted ascending by name. Without this flag, wildcard characters have no special meaning and are interpreted literally.
SORT=method
Sort the contents of each directory traversed (via MAXDEPTH) by method, which defaults to name. The possible values are:
- none: Do not sort.
- name: Sort by name, case-sensitively.
- size: Sort by size, then by name.
- atime: Sort by last-accessed time, then by name.
- mtime: Sort by last-modified time, then by name.
- ctime: Sort by last-changed time, then by name.
- version: Natural file sort by version number(s) in the name, same as <sort $name file rcase>. Added in version 8.01.1669155182 20221122.
Note that each traversed directory's contents are sorted separately, not the entire result set together.
ASC Sort each descended directory's files in ascending order (the default).
DESC Sort each descended directory's files in descending order.
RESOLVEUSERNAMES
Resolve user and group names into $ret.owner and $ret.group. With this flag off, these variables are set empty. Not resolving names saves time and resources, e.g. potential calls to NIS or the Windows domain controller, when these variables are not needed. The flag is off by default (and only supported) in syntaxversion 8 and later, and implicitly on in syntaxversion 7 and earlier.

DIAGNOSTICS
stat returns the file path in $ret, plus various other $ret.... variables as listed above. If looping syntax (or self-closing in version 8.00.1645136290 20220217 and later) is used, $loop and $next are set as well as the other variables.

EXAMPLE

<stat "/very/important/file"[ /]>
<IF $ret.err neq "">
  Could not find file: $ret.err
</IF>

Contents of directory $dir:

<stat 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>
</stat>

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 emulates an ls or dir of the directory $dir, and 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 ALL ensures that "." and ".." are returned too.

CAVEATS
The stat function was added in version 3.01.982000000 20010212.

Certain return variables are platform-dependent, such as $ret.dev, $ret.symlink and $ret.sympath.

Using the FOLLOWSYM option can cause repetitive, copious and useless return values if symbolic links point to directories, as the resulting filesystem loop will be followed.

The syntaxversion pragma (here) affects this statement: in version 8 and later syntax, the statement must be self-closed (non-looping) or have a matching close tag (looping).