1.\" $NetBSD: stat.1,v 1.28 2010/04/05 21:25:01 joerg Exp $ 2.\" 3.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Andrew Brown and Jan Schaumann. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" $FreeBSD: head/usr.bin/stat/stat.1 267773 2014-06-23 08:23:05Z bapt $ 31.\" 32.Dd February 28, 2016 33.Dt STAT 1 34.Os 35.Sh NAME 36.Nm stat , 37.Nm readlink 38.Nd display file status 39.Sh SYNOPSIS 40.Nm 41.Op Fl FHLnq 42.Op Fl f Ar format | Fl l | r | s | x 43.Op Fl t Ar timefmt 44.Op Ar 45.Nm readlink 46.Op Fl fn 47.Op Ar 48.Sh DESCRIPTION 49The 50.Nm 51utility displays information about the file pointed to by 52.Ar file . 53Read, write, or execute permissions of the named file are not required, but 54all directories listed in the pathname leading to the file must be 55searchable. 56If no argument is given, 57.Nm 58displays information about the file descriptor for standard input. 59.Pp 60When invoked as 61.Nm readlink , 62only the target of the symbolic link is printed. 63If the given argument is not a symbolic link and the 64.Fl f 65option is not specified, 66.Nm readlink 67will print nothing and exit with an error. 68If the 69.Fl f 70option is specified, the output is canonicalized by following every symlink 71in every component of the given path recursively. 72.Nm readlink 73will resolve both absolute and relative paths, and return the absolute pathname 74corresponding to 75.Ar file . 76In this case, the argument does not need to be a symbolic link. 77.Pp 78The information displayed is obtained by calling 79.Xr lstat 2 80with the given argument and evaluating the returned structure. 81The default format displays the 82.Fa st_dev , 83.Fa st_ino , 84.Fa st_mode , 85.Fa st_nlink , 86.Fa st_uid , 87.Fa st_gid , 88.Fa st_rdev , 89.Fa st_size , 90.Fa st_atime , 91.Fa st_mtime , 92.Fa st_ctime , 93.Fa st_blksize , 94.Fa st_blocks , 95and 96.Fa st_flags 97fields, in that order. 98.Pp 99The options are as follows: 100.Bl -tag -width indent 101.It Fl F 102As in 103.Xr ls 1 , 104display a slash 105.Pq Ql / 106immediately after each pathname that is a directory, 107an asterisk 108.Pq Ql * 109after each that is executable, 110an at sign 111.Pq Ql @ 112after each symbolic link, 113a percent sign 114.Pq Ql % 115after each whiteout, 116an equal sign 117.Pq Ql = 118after each socket, 119and a vertical bar 120.Pq Ql | 121after each that is a FIFO. 122The use of 123.Fl F 124implies 125.Fl l . 126.It Fl H 127Treat each argument as the hexadecimal representation of an NFS file handle, 128and use 129.Xr fhstat 2 130instead of 131.Xr lstat 2 . 132This requires root privileges. 133.It Fl L 134Use 135.Xr stat 2 136instead of 137.Xr lstat 2 . 138The information reported by 139.Nm 140will refer to the target of 141.Ar file , 142if file is a symbolic link, and not to 143.Ar file 144itself. 145If the link is broken or the target does not exist, 146fall back on 147.Xr lstat 2 148and report information about the link. 149.It Fl n 150Do not force a newline to appear at the end of each piece of output. 151.It Fl q 152Suppress failure messages if calls to 153.Xr stat 2 154or 155.Xr lstat 2 156fail. 157When run as 158.Nm readlink , 159error messages are automatically suppressed. 160.It Fl f Ar format 161Display information using the specified format. 162See the 163.Sx Formats 164section for a description of valid formats. 165.It Fl l 166Display output in 167.Nm ls Fl lT 168format. 169.It Fl r 170Display raw information. 171That is, for all the fields in the 172.Vt stat 173structure, 174display the raw, numerical value (for example, times in seconds since the 175epoch, etc.). 176.It Fl s 177Display information in 178.Dq shell output 179format, 180suitable for initializing variables. 181.It Fl x 182Display information in a more verbose way as known from some 183.Tn Linux 184distributions. 185.It Fl t Ar timefmt 186Display timestamps using the specified format. 187This format is 188passed directly to 189.Xr strftime 3 . 190.El 191.Ss Formats 192Format strings are similar to 193.Xr printf 3 194formats in that they start with 195.Cm % , 196are then followed by a sequence of formatting characters, and end in 197a character that selects the field of the 198.Vt "struct stat" 199which is to be formatted. 200If the 201.Cm % 202is immediately followed by one of 203.Cm n , t , % , 204or 205.Cm @ , 206then a newline character, a tab character, a percent character, 207or the current file number is printed, otherwise the string is 208examined for the following: 209.Pp 210Any of the following optional flags: 211.Bl -tag -width indent 212.It Cm # 213Selects an alternate output form for octal and hexadecimal output. 214Non-zero octal output will have a leading zero, and non-zero 215hexadecimal output will have 216.Dq Li 0x 217prepended to it. 218.It Cm + 219Asserts that a sign indicating whether a number is positive or negative 220should always be printed. 221Non-negative numbers are not usually printed 222with a sign. 223.It Cm - 224Aligns string output to the left of the field, instead of to the right. 225.It Cm 0 226Sets the fill character for left padding to the 227.Ql 0 228character, instead of a space. 229.It space 230Reserves a space at the front of non-negative signed output fields. 231A 232.Sq Cm + 233overrides a space if both are used. 234.El 235.Pp 236Then the following fields: 237.Bl -tag -width indent 238.It Ar size 239An optional decimal digit string specifying the minimum field width. 240.It Ar prec 241An optional precision composed of a decimal point 242.Sq Cm \&. 243and a decimal digit string that indicates the maximum string length, 244the number of digits to appear after the decimal point in floating point 245output, or the minimum number of digits to appear in numeric output. 246.It Ar fmt 247An optional output format specifier which is one of 248.Cm D , O , U , X , F , 249or 250.Cm S . 251These represent signed decimal output, octal output, unsigned decimal 252output, hexadecimal output, floating point output, and string output, 253respectively. 254Some output formats do not apply to all fields. 255Floating point output only applies to 256.Vt timespec 257fields (the 258.Cm a , m , 259and 260.Cm c 261fields). 262.Pp 263The special output specifier 264.Cm S 265may be used to indicate that the output, if 266applicable, should be in string format. 267May be used in combination with: 268.Bl -tag -width indent 269.It Cm amc 270Display date in 271.Xr strftime 3 272format. 273.It Cm dr 274Display actual device name. 275.It Cm f 276Display the flags of 277.Ar file 278as in 279.Nm ls Fl lTdo . 280.It Cm gu 281Display group or user name. 282.It Cm p 283Display the mode of 284.Ar file 285as in 286.Nm ls Fl lTd . 287.It Cm N 288Displays the name of 289.Ar file . 290.It Cm T 291Displays the type of 292.Ar file . 293.It Cm Y 294Insert a 295.Dq Li " -\*[Gt] " 296into the output. 297Note that the default output format 298for 299.Cm Y 300is a string, but if specified explicitly, these four characters are 301prepended. 302.El 303.It Ar sub 304An optional sub field specifier (high, middle, low). 305Only applies to 306the 307.Cm p , d , r , 308and 309.Cm T 310output formats. 311It can be one of the following: 312.Bl -tag -width indent 313.It Cm H 314.Dq High 315\[em] 316specifies the major number for devices from 317.Cm r 318or 319.Cm d , 320the 321.Dq user 322bits for permissions from the string form of 323.Cm p , 324the file 325.Dq type 326bits from the numeric forms of 327.Cm p , 328and the long output form of 329.Cm T . 330.It Cm L 331.Dq Low 332\[em] 333specifies the minor number for devices from 334.Cm r 335or 336.Cm d , 337the 338.Dq other 339bits for permissions from the string form of 340.Cm p , 341the 342.Dq user , 343.Dq group , 344and 345.Dq other 346bits from the numeric forms of 347.Cm p , 348and the 349.Nm ls Fl F 350style output character for file type when used with 351.Cm T 352(the use of 353.Cm L 354for this is optional). 355.It Cm M 356.Dq Middle 357\[em] 358specifies the 359.Dq group 360bits for permissions from the 361string output form of 362.Cm p , 363or the 364.Dq suid , 365.Dq sgid , 366and 367.Dq sticky 368bits for the numeric forms of 369.Cm p . 370.El 371.It Ar datum 372A required field specifier, being one of the following: 373.Bl -tag -width indent 374.It Cm d 375Device upon which 376.Ar file 377resides 378.Pq Fa st_dev . 379.It Cm i 380.Ar file Ns 's 381inode number 382.Pq Fa st_ino . 383.It Cm p 384File type and permissions 385.Pq Fa st_mode . 386.It Cm l 387Number of hard links to 388.Ar file 389.Pq Fa st_nlink . 390.It Cm u , g 391User ID and group ID of 392.Ar file Ns 's 393owner 394.Pq Fa st_uid , st_gid . 395.It Cm r 396Device number for character and block device special files 397.Pq Fa st_rdev . 398.It Cm a , m , c 399The time 400.Ar file 401was last accessed or modified, or when the inode was last changed 402.Pq Fa st_atime , st_mtime , st_ctime . 403.It Cm z 404The size of 405.Ar file 406in bytes 407.Pq Fa st_size . 408.It Cm b 409Number of blocks allocated for 410.Ar file 411.Pq Fa st_blocks . 412.It Cm k 413Optimal file system I/O operation block size 414.Pq Fa st_blksize . 415.It Cm f 416User defined flags for 417.Ar file . 418.It Cm v 419Inode generation number 420.Pq Fa st_gen . 421.El 422.Pp 423The following five field specifiers are not drawn directly from the 424data in 425.Vt "struct stat" , 426but are: 427.Bl -tag -width indent 428.It Cm N 429The name of the file. 430.It Cm R 431The absolute pathname corresponding to the file. 432.It Cm T 433The file type, either as in 434.Nm ls Fl F 435or in a more descriptive form if the 436.Ar sub 437field specifier 438.Cm H 439is given. 440.It Cm Y 441The target of a symbolic link. 442.It Cm Z 443Expands to 444.Dq major,minor 445from the 446.Va rdev 447field for character or block 448special devices and gives size output for all others. 449.El 450.El 451.Pp 452Only the 453.Cm % 454and the field specifier are required. 455Most field specifiers default to 456.Cm U 457as an output form, with the 458exception of 459.Cm p 460which defaults to 461.Cm O ; 462.Cm a , m , 463and 464.Cm c 465which default to 466.Cm D ; 467and 468.Cm Y , T , 469and 470.Cm N 471which default to 472.Cm S . 473.Sh EXIT STATUS 474.Ex -std stat readlink 475.Sh EXAMPLES 476If no options are specified, the default format is 477"%d %i %Sp %l %Su %Sg %r %z \e"%Sa\e" \e"%Sm\e" \e"%Sc\e" %k %b %#Xf %N". 478.Bd -literal -offset indent 479\*[Gt] stat /tmp/bar 4800 78852 -rw-r--r-- 1 root wheel 0 0 "Jul 8 10:26:03 2004" "Jul 8 10:26:03 2004" "Jul 8 10:28:13 2004" 16384 0 0 /tmp/bar 481.Ed 482.Pp 483Given a symbolic link 484.Dq foo 485that points from 486.Pa /tmp/foo 487to 488.Pa / , 489you would use 490.Nm 491as follows: 492.Bd -literal -offset indent 493\*[Gt] stat -F /tmp/foo 494lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] / 495 496\*[Gt] stat -LF /tmp/foo 497drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/ 498.Ed 499.Pp 500To initialize some shell variables, you could use the 501.Fl s 502flag as follows: 503.Bd -literal -offset indent 504\*[Gt] csh 505% eval set `stat -s .cshrc` 506% echo $st_size $st_mtimespec 5071148 1015432481 508 509\*[Gt] sh 510$ eval $(stat -s .profile) 511$ echo $st_size $st_mtimespec 5121148 1015432481 513.Ed 514.Pp 515In order to get a list of file types including files pointed to if the 516file is a symbolic link, you could use the following format: 517.Bd -literal -offset indent 518$ stat -f "%N: %HT%SY" /tmp/* 519/tmp/bar: Symbolic Link -\*[Gt] /tmp/foo 520/tmp/output25568: Regular File 521/tmp/blah: Directory 522/tmp/foo: Symbolic Link -\*[Gt] / 523.Ed 524.Pp 525In order to get a list of the devices, their types and the major and minor 526device numbers, formatted with tabs and linebreaks, you could use the 527following format: 528.Bd -literal -offset indent 529stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/* 530[...] 531Name: /dev/xpt0 532 Type: Character Device 533 Major: 28 534 Minor: 0 535 536Name: /dev/zero 537 Type: Character Device 538 Major: 2 539 Minor: 12 540.Ed 541.Pp 542In order to determine the permissions set on a file separately, you could use 543the following format: 544.Bd -literal -offset indent 545\*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" . 546drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x 547.Ed 548.Pp 549In order to determine the three files that have been modified most recently, 550you could use the following format: 551.Bd -literal -offset indent 552\*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2- 553Apr 25 11:47:00 2002 /tmp/blah 554Apr 25 10:36:34 2002 /tmp/bar 555Apr 24 16:47:35 2002 /tmp/foo 556.Ed 557.Pp 558To display a file's modification time: 559.Bd -literal -offset indent 560\*[Gt] stat -f %m /tmp/foo 5611177697733 562.Ed 563.Pp 564To display the same modification time in a readable format: 565.Bd -literal -offset indent 566\*[Gt] stat -f %Sm /tmp/foo 567Apr 27 11:15:33 2007 568.Ed 569.Pp 570To display the same modification time in a readable and sortable format: 571.Bd -literal -offset indent 572\*[Gt] stat -f %Sm -t %Y%m%d%H%M%S /tmp/foo 57320070427111533 574.Ed 575.Pp 576To display the same in UTC: 577.Bd -literal -offset indent 578\*[Gt] sh 579$ TZ= stat -f %Sm -t %Y%m%d%H%M%S /tmp/foo 58020070427181533 581.Ed 582.Sh SEE ALSO 583.Xr file 1 , 584.Xr ls 1 , 585.Xr lstat 2 , 586.Xr readlink 2 , 587.Xr stat 2 , 588.Xr printf 3 , 589.Xr strftime 3 590.Sh HISTORY 591The 592.Nm 593utility appeared in 594.Nx 1.6 595and 596.Fx 4.10 . 597.Sh AUTHORS 598.An -nosplit 599The 600.Nm 601utility was written by 602.An Andrew Brown Aq Mt atatat@NetBSD.org . 603This man page was written by 604.An Jan Schaumann Aq Mt jschauma@NetBSD.org . 605