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