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