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$ 31.\" 32.Dd April 22, 2012 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_birthtime , 94.Fa st_blksize , 95.Fa st_blocks , 96and 97.Fa st_flags 98fields, in that order. 99.Pp 100The options are as follows: 101.Bl -tag -width indent 102.It Fl F 103As in 104.Xr ls 1 , 105display a slash 106.Pq Ql / 107immediately after each pathname that is a directory, 108an asterisk 109.Pq Ql * 110after each that is executable, 111an at sign 112.Pq Ql @ 113after each symbolic link, 114a percent sign 115.Pq Ql % 116after each whiteout, 117an equal sign 118.Pq Ql = 119after each socket, 120and a vertical bar 121.Pq Ql | 122after each that is a FIFO. 123The use of 124.Fl F 125implies 126.Fl l . 127.It Fl H 128Treat each argument as the hexadecimal representation of an NFS file handle, 129and use 130.Xr fhstat 2 131instead of 132.Xr lstat 2 . 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 , B 399The time 400.Ar file 401was last accessed or modified, or when the inode was last changed, or 402the birth time of the inode 403.Pq Fa st_atime , st_mtime , st_ctime , st_birthtime . 404.It Cm z 405The size of 406.Ar file 407in bytes 408.Pq Fa st_size . 409.It Cm b 410Number of blocks allocated for 411.Ar file 412.Pq Fa st_blocks . 413.It Cm k 414Optimal file system I/O operation block size 415.Pq Fa st_blksize . 416.It Cm f 417User defined flags for 418.Ar file . 419.It Cm v 420Inode generation number 421.Pq Fa st_gen . 422.El 423.Pp 424The following five field specifiers are not drawn directly from the 425data in 426.Vt "struct stat" , 427but are: 428.Bl -tag -width indent 429.It Cm N 430The name of the file. 431.It Cm R 432The absolute pathname corresponding to the file. 433.It Cm T 434The file type, either as in 435.Nm ls Fl F 436or in a more descriptive form if the 437.Ar sub 438field specifier 439.Cm H 440is given. 441.It Cm Y 442The target of a symbolic link. 443.It Cm Z 444Expands to 445.Dq major,minor 446from the 447.Va rdev 448field for character or block 449special devices and gives size output for all others. 450.El 451.El 452.Pp 453Only the 454.Cm % 455and the field specifier are required. 456Most field specifiers default to 457.Cm U 458as an output form, with the 459exception of 460.Cm p 461which defaults to 462.Cm O ; 463.Cm a , m , 464and 465.Cm c 466which default to 467.Cm D ; 468and 469.Cm Y , T , 470and 471.Cm N 472which default to 473.Cm S . 474.Sh EXIT STATUS 475.Ex -std stat readlink 476.Sh EXAMPLES 477If no options are specified, the default format is 478"%d %i %Sp %l %Su %Sg %r %z \e"%Sa\e" \e"%Sm\e" \e"%Sc\e" \e"%SB\e" %k %b %#Xf %N". 479.Bd -literal -offset indent 480\*[Gt] stat /tmp/bar 4810 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" "Jan 1 09:00:00 1970" 16384 0 0 /tmp/bar 482.Ed 483.Pp 484Given a symbolic link 485.Dq foo 486that points from 487.Pa /tmp/foo 488to 489.Pa / , 490you would use 491.Nm 492as follows: 493.Bd -literal -offset indent 494\*[Gt] stat -F /tmp/foo 495lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] / 496 497\*[Gt] stat -LF /tmp/foo 498drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/ 499.Ed 500.Pp 501To initialize some shell variables, you could use the 502.Fl s 503flag as follows: 504.Bd -literal -offset indent 505\*[Gt] csh 506% eval set `stat -s .cshrc` 507% echo $st_size $st_mtimespec 5081148 1015432481 509 510\*[Gt] sh 511$ eval $(stat -s .profile) 512$ echo $st_size $st_mtimespec 5131148 1015432481 514.Ed 515.Pp 516In order to get a list of file types including files pointed to if the 517file is a symbolic link, you could use the following format: 518.Bd -literal -offset indent 519$ stat -f "%N: %HT%SY" /tmp/* 520/tmp/bar: Symbolic Link -\*[Gt] /tmp/foo 521/tmp/output25568: Regular File 522/tmp/blah: Directory 523/tmp/foo: Symbolic Link -\*[Gt] / 524.Ed 525.Pp 526In order to get a list of the devices, their types and the major and minor 527device numbers, formatted with tabs and linebreaks, you could use the 528following format: 529.Bd -literal -offset indent 530stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/* 531[...] 532Name: /dev/wt8 533 Type: Block Device 534 Major: 3 535 Minor: 8 536 537Name: /dev/zero 538 Type: Character Device 539 Major: 2 540 Minor: 12 541.Ed 542.Pp 543In order to determine the permissions set on a file separately, you could use 544the following format: 545.Bd -literal -offset indent 546\*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" . 547drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x 548.Ed 549.Pp 550In order to determine the three files that have been modified most recently, 551you could use the following format: 552.Bd -literal -offset indent 553\*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2- 554Apr 25 11:47:00 2002 /tmp/blah 555Apr 25 10:36:34 2002 /tmp/bar 556Apr 24 16:47:35 2002 /tmp/foo 557.Ed 558.Pp 559To display a file's modification time: 560.Bd -literal -offset indent 561\*[Gt] stat -f %m /tmp/foo 5621177697733 563.Ed 564.Pp 565To display the same modification time in a readable format: 566.Bd -literal -offset indent 567\*[Gt] stat -f %Sm /tmp/foo 568Apr 27 11:15:33 2007 569.Ed 570.Pp 571To display the same modification time in a readable and sortable format: 572.Bd -literal -offset indent 573\*[Gt] stat -f %Sm -t %Y%m%d%H%M%S /tmp/foo 57420070427111533 575.Ed 576.Pp 577To display the same in UTC: 578.Bd -literal -offset indent 579\*[Gt] sh 580$ TZ= stat -f %Sm -t %Y%m%d%H%M%S /tmp/foo 58120070427181533 582.Ed 583.Sh SEE ALSO 584.Xr file 1 , 585.Xr ls 1 , 586.Xr lstat 2 , 587.Xr readlink 2 , 588.Xr stat 2 , 589.Xr printf 3 , 590.Xr strftime 3 591.Sh HISTORY 592The 593.Nm 594utility appeared in 595.Nx 1.6 596and 597.Fx 4.10 . 598.Sh AUTHORS 599.An -nosplit 600The 601.Nm 602utility was written by 603.An Andrew Brown 604.Aq atatat@NetBSD.org . 605This man page was written by 606.An Jan Schaumann 607.Aq jschauma@NetBSD.org . 608