.. zsh-module-meta::
   :name: zsh/stat
   :summary: A builtin command interface to the ``stat`` system call.

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

.. index:: single: zstat; Function

.. index:: single: stat; Function

.. index:: single: files, listing; Command

.. index:: single: files, examining; Command

``zstat`` [ ``-gnNolLtTrs`` ] [ ``-f`` :var:`fd` ] [ ``-H`` :var:`hash` ] [ ``-A`` :var:`array` ] [ ``-F`` :var:`fmt` ]

      [ ``+``:var:`element` ] [ :var:`file` ... ]

``stat`` :var:`...`
    
    The command acts as a front end to the ``stat`` system call (see
    :manpage:`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 (:emphasis:`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 (```zstat +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`` :var:`array`
        
        Instead of displaying the results on standard
        output, assign them to an :var:`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 :var:`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`` :var:`hash`
        
        Similar to ``-A``, but instead assign the values to :var:`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`` :var:`fd`
        
        Use the file on file descriptor :var:`fd` instead of
        named files; no list of file names is allowed in this case.
        
    
    ``-F`` :var:`fmt`
        
        Supplies a ``strftime`` (see :manpage:`strftime(3)`) string for the
        formatting of the time elements.  The format string supports all of the
        zsh extensions (see the description of ``%D{``:var:`string`\ ``}``
        prompt escape in :zshsectref:`Simple Prompt Escapes <zshmisc>`).
        In particular, ``-F %s.%N`` can be used to show timestamps with nanosecond
        precision if supported by the system.
        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;
        arguments, and options other than ``-A``, are ignored.
        
    
    ``-L``
        
        Perform an ``lstat`` (see :manpage:`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 :manpage:`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.
        
    
    
    

