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