Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


STAT(1)                     General Commands Manual                    STAT(1)

NAME
     stat - display file status

SYNOPSIS
     stat [-FLnq] [-f format | -l | -r | -s | -x] [-t timefmt] [file ...]

DESCRIPTION
     The stat utility displays information about each file given by file.
     Read, write, or execute permissions for the named file are not required,
     but all directories listed in the pathname leading to the file must be
     searchable.

     If no file argument is given, stat displays information about the file
     descriptor for standard input.  In this case the -L option is ignored,
     and stat uses fstat(2) rather than lstat(2) or stat(2) to obtain
     information.  The `file name' (and also the `path name') in this case is
     `(stdin)'.  The file number (`%@') will be zero.

     Otherwise the information displayed is obtained by calling lstat(2) (or
     stat(2) with -L) with each given argument in turn and evaluating the
     returned structure.

     The default format displays the st_dev, st_ino, st_mode, st_nlink,
     st_uid, st_gid, st_rdev, st_size, st_atime, st_mtime, st_ctime,
     st_birthtime, st_blksize, st_blocks, and st_flags fields, in that order.

     The options are as follows:

     -F          As in ls(1), display a slash (`/') immediately after each
                 pathname that is a directory, an asterisk (`*') after each
                 that is executable, an at sign (`@') after each symbolic
                 link, a percent sign (`%') after each whiteout, an equal sign
                 (`=') after each socket, and a vertical bar (`|') after each
                 that is a FIFO.  The use of -F implies -l.

     -f format   Display information using the specified format.  See the
                 FORMATS section for a description of valid formats.

     -L          Use stat(2) instead of lstat(2).  The information reported by
                 stat will refer to the target of file, if file is a symbolic
                 link, rather than to file itself.

     -l          Display output in ls -lT format.

     -n          Do not force a newline to appear at the end of each piece of
                 output.

     -q          Suppress failure messages if calls to fstat(2), lstat(2),
                 readlink(2), realpath(3), or stat(2) fail.

     -r          Display raw information.  That is, for all the fields in the
                 stat-structure, display the raw, numerical value (for
                 example, times in seconds since the epoch, etc.)

     -s          Display information in "shell command" output format,
                 suitable for initializing variables.  This is equivalent to
                 specifying

                 FMT="st_dev=%d st_ino=%i st_mode=%#p st_nlink=%l"
                 FMT="$FMT st_uid=%u st_gid=%g st_rdev=%r st_size=%z"
                 FMT="$FMT st_atime=%Sa st_mtime=%Sm st_ctime=%Sc"
                 FMT="$FMT st_birthtime=%SB st_blksize=%k st_blocks=%b"
                 FMT="$FMT st_flags=%f"
                 stat -t %s -f "$FMT" .

                 The timefmt may be altered from the default for -s (`%s') by
                 also using the -t option.  Note that if you use a timefmt
                 that contains embedded whitespace or shell meta-characters,
                 you will need to include appropriate quoting in the -t
                 format, or supply an explicit format (-f), rather than -s,
                 with the format containing appropriate quoting so the output
                 remains valid.

     -t timefmt  Display timestamps, when to be output in string format, using
                 the specified format.  This format is passed directly to
                 strftime(3) with the extension that `%f' prints nanoseconds
                 if available.

     -x          Display information in a more verbose way as seen from some
                 Linux distributions.

   FORMATS
     Format strings are similar to printf(3) formats in that they contain
     character data, which is simply output, interspersed with data
     conversions which start with %, are then followed by a sequence of
     formatting characters, and end in a character that selects the datum, the
     field of the struct stat, or other data, which is to be formatted.  If
     the % is immediately followed by one of n, t, %, or @, then a newline
     character, a tab character, a percent character, or the current file
     number in the argument list is printed.  Otherwise the string is examined
     for the following:

     Any of the following optional flags in any order:

     #           Selects an alternate output form for string, octal and
                 hexadecimal output.  String output will be encoded in vis(3)
                 style.  Octal output will have a leading zero.  Non-zero
                 hexadecimal output will have `0x' prepended to it.

     +           Asserts that a sign indicating whether a number is positive
                 or negative should always be printed.  Non-negative numbers
                 are not usually printed with a sign.

     -           Aligns string output to the left of the field, instead of to
                 the right.

     0           Sets the fill character for left padding to the 0 character,
                 instead of a space.

     space       Reserves a space at the front of non-negative signed output
                 fields.  A `+' overrides a space if both are used.

     Then followed by the following fields in the following order:

     size          An optional decimal digit string specifying the minimum
                   field width.  Note that a leading zero is treated as the
                   `0' flag (above), subsequent embedded zeroes are part of
                   the size.

     prec          An optional precision composed of a decimal point `.' and a
                   decimal digit string that indicates the maximum string
                   length, the number of digits to appear after the decimal
                   point in floating point output, or the minimum number of
                   digits to appear in other numeric output.

     fmt           An optional output format specifier which is one of D, O,
                   U, X, F, or S.  These represent signed decimal output,
                   octal output, unsigned decimal output, hexadecimal output,
                   floating point output, and string output, respectively.
                   Some output formats do not apply to all fields.  Floating
                   point output only applies to timespec fields (the a, m, and
                   c fields).

                   The special output format specifier S may be used to
                   indicate that the output, if applicable, should be in
                   string format.  May be used in combination with the
                   following field specifiers:

                   a, m, c     Display date in strftime(3) format with the
                               extension that `%f' prints nanoseconds if
                               available.

                   d, r        Display actual device name.

                   g, u        Display group or user name.

                   p           Display the mode of file symbolically, as in ls
                               -lTd.

                   N           Displays the name of file.

                   T           Displays the type of file.

                   R, Y        Insert a ` -> ' into the output.  Note that the
                               default output formats for Y and R are strings,
                               if S is specified explicitly, these four
                               characters are prepended.

     sub           An optional sub field specifier: high, middle, or low.
                   Only applies to the d, N, p, r, T, and z output field
                   specifiers.  It can be one of the following:

                   H           "High" subfield of datum:
                               d, r        Major number for devices
                               N           Directory path of the file, similar
                                           to what dirname(1) would show
                               p           "User" bits from the string form of
                                           permissions, or the file "type"
                                           bits from the numeric forms
                               T           The long output form of file type
                               z           File size, rounded to the nearest
                                           gigabyte

                   M           "Middle" subfield of datum:
                               p           The "group" bits from the string
                                           form of permissions, or the "suid",
                                           "sgid", and "sticky" bits from the
                                           numeric forms
                               z           File size, rounded to the nearest
                                           megabyte

                   L           "Low" subfield of datum:
                               d, r        Minor number for devices
                               N           Base filename of the file, similar
                                           to what basename(1) would show
                               p           The "other" bits from the string
                                           form of permissions, or the "user",
                                           "group", and "other" bits from the
                                           numeric forms
                               T           The ls -F style output character
                                           for file type (the use of L here is
                                           optional)
                               z           File size, rounded to the nearest
                                           kilobyte

     datum         A required field specifier, ending the conversion
                   specification, being one of the following:

                   d           Device upon which file resides (st_dev).

                   i           file's inode number (st_ino).

                   p           File type and permissions (st_mode).

                   l           Number of hard links to file (st_nlink).

                   u, g        User-id and group-id of file's owner (st_uid,
                               st_gid).

                   r           Device number for character and block device
                               special files (st_rdev).

                   a, m, c, B  The time file was last accessed or modified, or
                               when its inode was last changed, or the birth
                               time of the inode (st_atime, st_mtime,
                               st_ctime, st_birthtime).

                   z           The size of file in bytes (st_size).

                   b           Number of blocks allocated for file
                               (st_blocks).

                   k           Optimal file system I/O operation block size
                               (st_blksize).

                   f           User defined flags for file (st_flags).

                   v           Inode generation number (st_gen).

                   The following five field specifiers are not drawn directly
                   from the data in struct stat, but are:

                   N           The name of the file.

                   R           The absolute pathname corresponding to the
                               file.

                   T           The file type, either as in ls -F or in a more
                               descriptive form if the sub field specifier H
                               is given.

                   Y           The target of a symbolic link.

                   Z           Expands to "major,minor" (that is, `%Hr,%-Lr')
                               for character or block special devices, and
                               gives size output (`%z') for all other file
                               types.  A specified field width applies to the
                               overall result (approximately half each for the
                               two device file sub-fields), but precision,
                               output format, and flags are used separately
                               for each conversion made (but note the `-' in
                               the `%-Lr' conversion.)

     Only the `%' and the datum (field specifier) are required.  Most field
     specifiers default to U as an output format, with the exception of p
     which defaults to O; a, m, and c which default to D; and Y, T, R, and N,
     which default to S.

EXIT STATUS
     The stat utility exits 0 on success, and >0 if an error occurs.

EXAMPLES
     If no options are specified, the default format is:

           %d %i %Sp %l %Su %Sg %r %z "%Sa" "%Sm" "%Sc" "%SB" %k %b %#Xf %N

     Thus:
           > stat /tmp/bar
           0 78852 -rw-r--r-- 1 root wheel -1 0 "Jul  8 10:26:03 2004" "Jul  8 10:26:03 2004" "Jul  8 10:28:13 2004" "Jan  1 09:00:00 1970" 16384 0 0 /tmp/bar

     This next example produces output very similar to that from find ... -ls,
     except that find(1) displays the time in a different format, and find(1)
     sometimes adds one or more spaces after the comma in "major,minor" for
     device nodes:

           > stat -f "%7i %6b %-11Sp %3l %-17Su %-17Sg %9Z %Sm %N%SY" /tmp/bar
             78852      0 -rw-r--r--    1 root              wheel                     0 Jul  8 10:26:03 2004 /tmp/bar

           > find /tmp/bar -ls -exit
             78852      0 -rw-r--r--    1 root              wheel                     0 Jul  8  2004 /tmp/bar

     This example produces output very similar to that from ls -lTd, except
     that ls(1) adjusts the column spacing differently when listing multiple
     files, and adds at least one space after the comma in "major,minor" for
     device nodes:

           > stat -f "%-11Sp %l %Su  %Sg  %Z %Sm %N%SY" /tmp/bar
           -rw-r--r--  1 root  wheel  0 Jul  8 10:26:03 2004 /tmp/bar

           > ls -lTd /tmp/bar
           -rw-r--r--  1 root  wheel  0 Jul  8 10:26:03 2004 /tmp/bar

     Given a symbolic link /tmp/foo that points to /, you would use stat as
     follows:

           > stat -F /tmp/foo
           lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -> /

           > stat -LF /tmp/foo
           drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/

     To initialize some shell variables, you could use the -s flag as follows:

           > csh
           % eval set `stat -s .cshrc`
           % echo $st_size $st_mtime
           1148 1015432481

           > sh
           $ eval $(stat -s .profile)
           $ echo $st_size $st_mtime
           1148 1015432481

     In order to get a list of the kind of files including files pointed to if
     the file is a symbolic link, you could use the following format:

           $ stat -f "%N: %HT%SY" /tmp/*
           /tmp/bar: Symbolic Link -> /tmp/foo
           /tmp/output25568: Regular File
           /tmp/blah: Directory
           /tmp/foo: Symbolic Link -> /

     In order to get a list of the devices, their types and the major and
     minor device numbers, formatted with tabs and line breaks, you could use
     the following format:

           stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
           [...]
           Name: /dev/wt8
                   Type: Block Device
                   Major: 3
                   Minor: 8

           Name: /dev/zero
                   Type: Character Device
                   Major: 2
                   Minor: 12

     In order to determine the permissions set on a file separately, you could
     use the following format:

           > stat -f "%Sp -> owner=%SHp group=%SMp other=%SLp" .
           drwxr-xr-x -> owner=rwx group=r-x other=r-x

     In order to determine the three files that have been modified most
     recently, you could use the following format:

           > stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
           Apr 25 11:47:00 2002 /tmp/blah
           Apr 25 10:36:34 2002 /tmp/bar
           Apr 24 16:47:35 2002 /tmp/foo

     User names, group names, and file names that contain spaces or other
     special characters may be encoded in vis(3) style, using the `#' flag:

           > ln -s 'target with spaces' 'link with spaces'
           > stat -f "%#N%#SY" 'link with spaces'
           link\swith\sspaces -> target\swith\sspaces

SEE ALSO
     basename(1), dirname(1), find(1), ls(1), readlink(1), fstat(2), lstat(2),
     readlink(2), stat(2), printf(3), realpath(3), strftime(3)

HISTORY
     The stat utility appeared in NetBSD 1.6.

AUTHORS
     The stat utility was written by Andrew Brown <atatat@NetBSD.org>.  This
     man page was written by Jan Schaumann <jschauma@NetBSD.org>.

NetBSD 10.99                     June 22, 2022                    NetBSD 10.99