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