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