zsh: The zsh/stat Module

Next: The zsh/system Module, Previous: The zsh/net/socket Module, Up: Zsh Modules [Contents][Index]

### 22.25 The zsh/stat Module

The `zsh/stat` module makes available one builtin command under two possible names:

`zstat` [ `-gnNolLtTrs` ] [ `-f` fd ] [ `-H` hash ] [ `-A` array ] [ `-F` fmt ]
`` [ `+`element ] [ file ... ]
`stat` ...

  The command acts as a front end to the `stat` system call (see man page stat(2)). The same command is provided with two names; as the name `stat` is often used by an external command it is recommended that only the `zstat` form of the command is used. This can be arranged by loading the module with the command ‘`zmodload -F zsh/stat b:zstat`’.

  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 ({No value for ‘dsbq’}`zstat +link`{No value for ‘dsq’}) 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. It’s important to note that this is the exact opposite from man page ls(1), etc.

  `-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.

Next: The zsh/system Module, Previous: The zsh/net/socket Module, Up: Zsh Modules [Contents][Index]