The zsh/stat Module
===================
The zsh/stat module makes available one builtin command:
stat [ -gnNolLtTrs ] [ -f FD ] [ -H HASH ] [ -A ARRAY ] [ -F FMT ] [ +ELEMENT ] [ FILE ... ]
The command acts as a front end to the stat system call (see man
page stat(2)). If the stat call fails, the appropriate system
error message printed and status 1 is returned. The fields of
struct stat give information about the files provided as arguments
to the command. In addition to those available from the stat
call, an extra element `link' is provided. These elements are:
device
The number of the device on which the file resides.
inode
The unique number of the file on this device (`_inode_'
number).
mode
The mode of the file; that is, the file's type and access
permissions. With the -s option, this will be returned as a
string corresponding to the first column in the display of
the ls -l command.
nlink
The number of hard links to the file.
uid
The user ID of the owner of the file. With the -s option,
this is displayed as a user name.
gid
The group ID of the file. With the -s option, this is
displayed as a group name.
rdev
The raw device number. This is only useful for special
devices.
size
The size of the file in bytes.
atime
mtime
ctime
The last access, modification and inode change times of the
file, respectively, as the number of seconds since midnight
GMT on 1st January, 1970. With the -s option, these are
printed as strings for the local time zone; the format can be
altered with the -F option, and with the -g option the times
are in GMT.
blksize
The number of bytes in one allocation block on the device on
which the file resides.
block
The number of disk blocks used by the file.
link
If the file is a link and the -L option is in effect, this
contains the name of the file linked to, otherwise it is
empty. Note that if this element is selected (``stat +link'')
then the -L option is automatically used.
A particular element may be selected by including its name
preceded by a `+' in the option list; only one element is allowed.
The element may be shortened to any unique set of leading
characters. Otherwise, all elements will be shown for all files.
Options:
-A ARRAY
Instead of displaying the results on standard output, assign
them to an ARRAY, one struct stat element per array element
for each file in order. In this case neither the name of the
element nor the name of the files appears in ARRAY unless the
-t or -n options were given, respectively. If -t is given,
the element name appears as a prefix to the appropriate array
element; if -n is given, the file name appears as a separate
array element preceding all the others. Other formatting
options are respected.
-H HASH
Similar to -A, but instead assign the values to HASH. The
keys are the elements listed above. If the -n option is
provided then the name of the file is included in the hash
with key name.
-f FD
Use the file on file descriptor FD instead of named files; no
list of file names is allowed in this case.
-F FMT
Supplies a strftime (see man page strftime(3)) string for the
formatting of the time elements. The -s option is implied.
-g
Show the time elements in the GMT time zone. The -s option
is implied.
-l
List the names of the type elements (to standard output or an
array as appropriate) and return immediately; options other
than -A and arguments are ignored.
-L
Perform an lstat (see man page lstat(2)) rather than a stat
system call. In this case, if the file is a link, information
about the link itself rather than the target file is returned.
This option is required to make the link element useful.
-n
Always show the names of files. Usually these are only shown
when output is to standard output and there is more than one
file in the list.
-N
Never show the names of files.
-o
If a raw file mode is printed, show it in octal, which is
more useful for human consumption than the default of
decimal. A leading zero will be printed in this case. Note
that this does not affect whether a raw or formatted file
mode is shown, which is controlled by the -r and -s options,
nor whether a mode is shown at all.
-r
Print raw data (the default format) alongside string data
(the -s format); the string data appears in parentheses after
the raw data.
-s
Print mode, uid, gid and the three time elements as strings
instead of numbers. In each case the format is like that of
ls -l.
-t
Always show the type names for the elements of struct stat.
Usually these are only shown when output is to standard
output and no individual element has been selected.
-T
Never show the type names of the struct stat elements.