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