1.\" $NetBSD: stat.1,v 1.4 2002/05/09 17:52:03 atatat Exp $ 2.\" 3.\" Copyright (c) 2002 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 April 24, 2002 38.Dt STAT 1 39.Os 40.Sh NAME 41.Nm stat 42.Nd display file status 43.Sh SYNOPSIS 44.Nm 45.Op Fl FLn 46.Oo 47.Fl f Ar format | 48.Fl l | 49.Fl r | 50.Fl s | 51.Fl x 52.Oc 53.Op Fl t Ar timefmt 54.Op Ar 55.Sh DESCRIPTION 56The 57.Nm 58utility displays information about the file pointed to by 59.Ar file . 60Read, write or execute permissions of the named file are not required, but 61all directories listed in the path name leading to the file must be 62searchable. If no argument is given, 63.Nm 64displays information about the file descriptor for standard input. 65.Pp 66The information displayed is obtained by calling 67.Xr lstat 2 68with the given argument and evaluating the returned structure. 69.Pp 70The options are as follows: 71.Bl -tag -width Ds 72.It Fl F 73As in 74.Ic ls , 75display a slash (/) immediately after each pathname that is a directory, an 76asterisk (*) after each that is executable, an at sign (@) after each symbolic 77link, a percent sign (%) after each whiteout, an equal sign (=) after each 78socket, and a vertical bar (|) after each that is a FIFO. The use of 79.Fl F 80implies 81.Fl l . 82.It Fl L 83Use 84.Xr stat 2 85instead of 86.Xr lstat 2 . 87The information reported by 88.Nm 89will refer to the target of 90.Ar file , 91if file is a symbolic link, and not to 92.Ar file 93itself. 94.It Fl n 95Do not force a newline to appear at the end of each piece of output. 96.It Fl f Ar format 97Display information using the specified format. See the FORMATS section 98for a description of valid formats. 99.It Fl l 100Display output in 101.Ic ls Fl lT 102format. 103.It Fl r 104Display raw information. That is, for all the fields in the stat-structure, 105display the raw, numerical value (for example, times in seconds since the 106epoch, etc.) 107.It Fl s 108Display information in ``shell output'', suitable for initializing variables. 109.It Fl x 110Display information in a more verbose way as known from some Linux 111distributions. 112.It Fl t Ar timefmt 113Display timestamps using the specified format. This format is 114passed directly to 115.Xr strftime 3 . 116.El 117.Ss FORMATS 118Format strings are similar to 119.Xr printf 3 120formats in that they start with 121.Cm % , 122are then followed by a sequence of formatting characters, and end in 123a character that selects the field of the struct stat which is to be 124formatted. If the 125.Cm % 126is immediately followed by one of 127.Cm n , 128.Cm t , 129.Cm % , 130or 131.Cm @ , 132then a newline character, a tab character, a percent character, 133or the current file number is printed, otherwise the string is 134examined for the following: 135.Pp 136Any of the following optional flags: 137.Bl -tag -width Ds 138.It Cm # 139Selects an alternate output form for octal and hexadecimal output. 140Non-zero octal output will have a leading zero, and non-zero 141hexadecimal output will have ``0x'' prepended to it. 142.It Cm + 143Asserts that a sign indicating whether a number is positive or negative 144should always be printed. Non-negative numbers are not usually printed 145with a sign. 146.It Cm - 147Aligns string output to the left of the field, instead of to the right. 148.It Cm 0 149Sets the fill character for left padding to the 0 character, instead of 150a space. 151.It space 152Reserves a space at the front of non-negative signed output fields. A 153.Sq Cm + 154overrides a space if both are used. 155.El 156.Pp 157Then the following fields: 158.Bl -tag -width Ds 159.It Cm size 160An optional decimal digit string specifying the minimum field width. 161.It Cm prec 162An optional precision composed of a decimal point 163.Sq Cm \&. 164and a decimal digit string that indicates the maximum string length, 165the number of digits to appear after the decimal point in floating point 166output, or the minimum number of digits to appear in numeric output. 167.It Cm fmt 168An optional output format specifier which is one of 169.Cm D , 170.Cm O , 171.Cm U , 172.Cm X , 173.Cm F , 174or 175.Cm S . 176These represent signed decimal output, octal output, unsigned decimal 177output, hexadecimal output, floating point output, and string output, 178respectively. Some output formats do not apply to all fields. 179Floating point output only applies to timespec fields (the 180.Cm a , 181.Cm m , 182and 183.Cm c 184fields). 185.Pp 186The special output specifier 187.Cm S 188may be used to indicate that the output, if 189applicable, should be in string format. May be used in combination with 190.Bl -tag -width Ds 191.It Cm amc 192Display date in strftime(3) format. 193.It Cm dr 194Display actual device name. 195.It Cm gu 196Display group or user name. 197.It Cm p 198Display the mode of 199.Ar file 200as in 201.Ic ls -lTd . 202.It Cm N 203Displays the name of 204.Ar file . 205.It Cm T 206Displays the type of 207.Ar file . 208.It Cm Y 209Insert a `` -\*[Gt] '' into the output. Note that the default output format 210for 211.Cm Y 212is a string, but if specified explicitly, these four characters are 213prepended. 214.El 215.It Cm sub 216An optional sub field specifier (high, middle, low). Only applies to 217the 218.Cm p , 219.Cm d , 220.Cm r , 221and 222.Cm T 223output formats. It can be one of the following: 224.Bl -tag -width Ds 225.It Cm H 226``High'' -- specifies the major number for devices from 227.Cm r 228or 229.Cm d , 230the ``user'' bits for permissions from the string form of 231.Cm p , 232the file ``type'' bits from the numeric forms of 233.Cm p , 234and the long output form of 235.Cm T . 236.It Cm L 237``Low'' -- specifies the minor number for devices from 238.Cm r 239or 240.Cm d , 241the ``other'' bits for permissions from the string form of 242.Cm p , 243the ``user'', ``group'', and ``other'' bits from the numeric forms of 244.Cm p , 245and the 246.Ic ls -F 247style output character for file type when used with 248.Cm T 249(the use of 250.Cm L 251for this is optional). 252.It Cm M 253``Middle'' -- specifies the ``group'' bits for permissions from the 254string output form of 255.Cm p , 256or the ``suid'', ``sgid'', and ``sticky'' bits for the numeric forms of 257.Cm p . 258.El 259.It Cm datum 260A required field specifier, being one of the following: 261.Bl -tag -width Ds 262.It Cm d 263Device upon which 264.Ar file 265resides. 266.It Cm i 267.Ar file Ap s 268inode number. 269.It Cm p 270File type and permissions. 271.It Cm l 272Number of hard links to 273.Ar file . 274.It Cm u , g 275User-id and group-id of 276.Ar file Ap s 277owner. 278.It Cm r 279Device number for character and block device special files. 280.It Cm a , m , c 281The time 282.Ar file 283was last accessed, modified, or of when the inode was last changed. 284.It Cm z 285The size of 286.Ar file 287in bytes. 288.It Cm b 289Number of blocks allocated for 290.Ar file . 291.It Cm k 292Optimal file system I/O operation block size. 293.It Cm f 294User defined flags for 295.Ar file . 296.It Cm v 297Inode generation number. 298.El 299.Pp 300The following four field specifiers are not drawn directly from the 301data in struct stat, but are 302.Bl -tag -width Ds 303.It Cm N 304The name of the file. 305.It Cm T 306The file type, either as in 307.Ic ls -F 308or in a more descriptive form if the sub field specifier 309.Cm H 310is given. 311.It Cm Y 312The target of a symbolic link. 313.It Cm Z 314Expands to ``major,minor'' from the rdev field for character or block 315special devices and gives size output for all others. 316.El 317.El 318.Pp 319Only the 320.Cm % 321and the field specifier are required. Most field 322specifiers default to 323.Cm U 324as an output form, with the 325exception of 326.Cm p 327which defaults to 328.Cm O , 329.Cm a , m , 330and 331.Cm c 332which default to 333.Cm D , 334and 335.Cm Y , T , 336and 337.Cm N , 338which default to 339.Cm S . 340.Sh EXIT STATUS 341.Nm 342exits 0 on success, and \*[Gt]0 if an error occurred. 343.Sh EXAMPLES 344Given a symbolic link ``foo'' that points from /tmp/foo to /, you would use 345.Nm 346as follows: 347.Bd -literal -offset indent 348\*[Gt] stat -F /tmp/foo 349lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] / 350 351\*[Gt] stat -LF /tmp/foo 352lrwxrwxrwx 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/ 353.Ed 354.Pp 355To initialize some shell-variables, you could use the 356.Fl s 357flag as follows: 358.Bd -literal -offset indent 359\*[Gt] csh 360% eval set `stat -s .cshrc` 361% echo $st_size $st_mtimespec 3621148 1015432481 363 364\*[Gt] sh 365$ eval $(stat -s .profile) 366$ echo $st_size $st_mtimespec 3671148 1015432481 368.Ed 369.Pp 370In order to get a list of the kind of files including files pointed to if the 371file is a symbolic link, you could use the following format: 372.Bd -literal -offset indent 373$ stat -f "%N: %HT%SY" /tmp/* 374/tmp/bar: Symbolic Link -\*[Gt] /tmp/foo 375/tmp/output25568: Regular File 376/tmp/blah: Directory 377/tmp/foo: Symbolic Link -\*[Gt] / 378.Ed 379.Pp 380In order to get a list of the devices, their types and the major and minor 381device numbers, formatted with tabs and linebreaks, you could use the 382following format: 383.Bd -literal -offset indent 384stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/* 385[...] 386Name: /dev/wt8 387 Type: Block Device 388 Major: 3 389 Minor: 8 390 391Name: /dev/zero 392 Type: Character Device 393 Major: 2 394 Minor: 12 395.Ed 396.Pp 397In order to determine the permissions set on a file separately, you could use 398the following format: 399.Bd -literal -offset indent 400\*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" . 401drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x 402.Ed 403.Pp 404In order to determine the three files that have been modified most recently, 405you could use the following format: 406.Bd -literal -offset indent 407\*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2- 408Apr 25 11:47:00 2002 /tmp/blah 409Apr 25 10:36:34 2002 /tmp/bar 410Apr 24 16:47:35 2002 /tmp/foo 411.Ed 412.Sh SEE ALSO 413.Xr file 1 , 414.Xr ls 1 , 415.Xr lstat 2 , 416.Xr readlink 2 , 417.Xr stat 2 , 418.Xr printf 3 , 419.Xr strftime 3 420.Sh HISTORY 421The 422.Nm 423utility appeared in 424.Nx 1.6 . 425.Sh AUTHORS 426The 427.Nm 428utility was written by Andrew Brown 429.Aq atatat@netbsd.org . 430This man page 431was written by Jan Schaumann 432.Aq jschauma@netbsd.org . 433