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