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