STAT(1) | General Commands Manual | STAT(1) |
stat
— display
file status
stat |
[-FLnq ] [-f
format | -l |
-r | -s |
-x ] [-t
timefmt] [file ...] |
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
/
’) 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-L
stat
will refer to the target of
file, if file is a symbolic
link, rather than to file itself. If
file is not a symbolic link,
stat(2) and
lstat(2) give the same
results, so this option is essentially a no-op in that case. If
file is a symbolic link, but the target of that link
does not exist, then stat
will fall back to using
lstat(2) and display details
of the symbolic link itself. This is the only situation where, when
-L
is used, the resulting data can refer to a
symbolic link.-l
ls
-lT
format.-n
-q
-r
-s
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%f
’ prints
nanoseconds if available.-x
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:
#
0x
’ prepended to it.+
-
0
+
’ overrides a space if both are
used.Then followed by the following fields in the following order:
0
’ flag (above), subsequent
embedded zeroes are part of the size..
’ 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.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
%f
’
prints nanoseconds if available.d
,
r
f
ls
-ldo
.g
,
u
p
ls -lTd
.N
T
R
,
Y
->
’
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.d
, N
,
p
, r
,
T
, and z
output field
specifiers. It can be one of the following:
H
M
L
d
,
r
N
p
T
ls -F
style output character for file
type (the use of L
here is optional)z
d
i
p
l
u
,
g
r
a
,
m
, c
,
B
z
b
k
f
v
The following five field specifiers are not drawn directly from the data in struct stat, but are:
N
R
T
ls -F
or in a more
descriptive form if the sub field specifier H
is given.Y
Z
,
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
.
The stat
utility exits 0 on
success, and >0 if an error occurs.
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
basename(1), dirname(1), find(1), ls(1), readlink(1), fstat(2), lstat(2), readlink(2), stat(2), printf(3), realpath(3), strftime(3)
The stat
utility appeared in
NetBSD 1.6.
The stat
utility was written by
Andrew Brown ⟨atatat@NetBSD.org⟩. This
man page was written by Jan Schaumann
⟨jschauma@NetBSD.org⟩.
May 3, 2025 | NetBSD 10.99 |