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 May 8, 2003 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 , B 354The time 355.Ar file 356was last accessed or modified, or when the inode was last changed, or 357the birth time of the inode. 358.It Cm z 359The size of 360.Ar file 361in bytes. 362.It Cm b 363Number of blocks allocated for 364.Ar file . 365.It Cm k 366Optimal file system I/O operation block size. 367.It Cm f 368User defined flags for 369.Ar file . 370.It Cm v 371Inode generation number. 372.El 373.Pp 374The following four field specifiers are not drawn directly from the 375data in 376.Vt "struct stat" , 377but are: 378.Bl -tag -width indent 379.It Cm N 380The name of the file. 381.It Cm T 382The file type, either as in 383.Nm ls Fl F 384or in a more descriptive form if the 385.Ar sub 386field specifier 387.Cm H 388is given. 389.It Cm Y 390The target of a symbolic link. 391.It Cm Z 392Expands to 393.Dq major,minor 394from the 395.Va rdev 396field for character or block 397special devices and gives size output for all others. 398.El 399.El 400.Pp 401Only the 402.Cm % 403and the field specifier are required. 404Most field specifiers default to 405.Cm U 406as an output form, with the 407exception of 408.Cm p 409which defaults to 410.Cm O , 411.Cm a , m , 412and 413.Cm c 414which default to 415.Cm D , 416and 417.Cm Y , T , 418and 419.Cm N 420which default to 421.Cm S . 422.Sh EXIT STATUS 423.Ex -std stat readlink 424.Sh EXAMPLES 425Given a symbolic link 426.Pa foo 427that points from 428.Pa /tmp/foo 429to 430.Pa / , 431you would use 432.Nm 433as follows: 434.Bd -literal -offset indent 435\*[Gt] stat -F /tmp/foo 436lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] / 437 438\*[Gt] stat -LF /tmp/foo 439drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/ 440.Ed 441.Pp 442To initialize some shell variables, you could use the 443.Fl s 444flag as follows: 445.Bd -literal -offset indent 446\*[Gt] csh 447% eval set `stat -s .cshrc` 448% echo $st_size $st_mtimespec 4491148 1015432481 450 451\*[Gt] sh 452$ eval $(stat -s .profile) 453$ echo $st_size $st_mtimespec 4541148 1015432481 455.Ed 456.Pp 457In order to get a list of the kind of files including files pointed to if the 458file is a symbolic link, you could use the following format: 459.Bd -literal -offset indent 460$ stat -f "%N: %HT%SY" /tmp/* 461/tmp/bar: Symbolic Link -\*[Gt] /tmp/foo 462/tmp/output25568: Regular File 463/tmp/blah: Directory 464/tmp/foo: Symbolic Link -\*[Gt] / 465.Ed 466.Pp 467In order to get a list of the devices, their types and the major and minor 468device numbers, formatted with tabs and linebreaks, you could use the 469following format: 470.Bd -literal -offset indent 471stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/* 472[...] 473Name: /dev/xpt0 474 Type: Character Device 475 Major: 28 476 Minor: 0 477 478Name: /dev/zero 479 Type: Character Device 480 Major: 2 481 Minor: 12 482.Ed 483.Pp 484In order to determine the permissions set on a file separately, you could use 485the following format: 486.Bd -literal -offset indent 487\*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" . 488drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x 489.Ed 490.Pp 491In order to determine the three files that have been modified most recently, 492you could use the following format: 493.Bd -literal -offset indent 494\*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2- 495Apr 25 11:47:00 2002 /tmp/blah 496Apr 25 10:36:34 2002 /tmp/bar 497Apr 24 16:47:35 2002 /tmp/foo 498.Ed 499.Sh SEE ALSO 500.Xr file 1 , 501.Xr ls 1 , 502.Xr lstat 2 , 503.Xr readlink 2 , 504.Xr stat 2 , 505.Xr printf 3 , 506.Xr strftime 3 507.Sh HISTORY 508The 509.Nm 510utility appeared in 511.Nx 1.6 512and 513.Fx 4.10 . 514.Sh AUTHORS 515.An -nosplit 516The 517.Nm 518utility was written by 519.An Andrew Brown 520.Aq atatat@NetBSD.org . 521This man page was written by 522.An Jan Schaumann 523.Aq jschauma@NetBSD.org . 524