1 .\" $NetBSD: stat.1,v 1.11 2003/05/08 13:07:10 wiz Exp $
3 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Andrew Brown and Jan Schaumann.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
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.
38 .Nd display file status
42 .Op Fl f Ar format | Fl l | r | s | x
51 utility displays information about the file pointed to by
53 Read, write or execute permissions of the named file are not required, but
54 all directories listed in the path name leading to the file must be
56 If no argument is given,
58 displays information about the file descriptor for standard input.
62 only the target of the symbolic link is printed.
63 If the given argument is not a symbolic link,
65 will print nothing and exit with an error.
67 The information displayed is obtained by calling
69 with the given argument and evaluating the returned structure.
71 The options are as follows:
72 .Bl -tag -width indent
78 immediately after each pathname that is a directory,
81 after each that is executable,
84 after each symbolic link,
93 after each that is a FIFO.
103 The information reported by
105 will refer to the target of
107 if file is a symbolic link, and not to
111 Do not force a newline to appear at the end of each piece of output.
113 Suppress failure messages if calls to
120 error messages are automatically suppressed.
122 Display information using the specified format.
125 section for a description of valid formats.
131 Display raw information.
132 That is, for all the fields in the
135 display the raw, numerical value (for example, times in seconds since the
138 Display information in
140 suitable for initializing variables.
142 Display information in a more verbose way as known from some
146 Display timestamps using the specified format.
152 Format strings are similar to
154 formats in that they start with
156 are then followed by a sequence of formatting characters, and end in
157 a character that selects the field of the
159 which is to be formatted.
162 is immediately followed by one of
166 then a newline character, a tab character, a percent character,
167 or the current file number is printed, otherwise the string is
168 examined for the following:
170 Any of the following optional flags:
171 .Bl -tag -width indent
173 Selects an alternate output form for octal and hexadecimal output.
174 Non-zero octal output will have a leading zero, and non-zero
175 hexadecimal output will have
179 Asserts that a sign indicating whether a number is positive or negative
180 should always be printed.
181 Non-negative numbers are not usually printed
184 Aligns string output to the left of the field, instead of to the right.
186 Sets the fill character for left padding to the
188 character, instead of a space.
190 Reserves a space at the front of non-negative signed output fields.
193 overrides a space if both are used.
196 Then the following fields:
197 .Bl -tag -width indent
199 An optional decimal digit string specifying the minimum field width.
201 An optional precision composed of a decimal point
203 and a decimal digit string that indicates the maximum string length,
204 the number of digits to appear after the decimal point in floating point
205 output, or the minimum number of digits to appear in numeric output.
207 An optional output format specifier which is one of
208 .Cm D , O , U , X , F ,
211 These represent signed decimal output, octal output, unsigned decimal
212 output, hexadecimal output, floating point output, and string output,
214 Some output formats do not apply to all fields.
215 Floating point output only applies to
223 The special output specifier
225 may be used to indicate that the output, if
226 applicable, should be in string format.
227 May be used in combination with:
228 .Bl -tag -width indent
234 Display actual device name.
241 Display group or user name.
257 Note that the default output format
260 is a string, but if specified explicitly, these four characters are
264 An optional sub field specifier (high, middle, low).
271 It can be one of the following:
272 .Bl -tag -width indent
276 specifies the major number for devices from
282 bits for permissions from the string form of
286 bits from the numeric forms of
288 and the long output form of
293 specifies the minor number for devices from
299 bits for permissions from the string form of
306 bits from the numeric forms of
310 style output character for file type when used with
314 for this is optional).
320 bits for permissions from the
321 string output form of
328 bits for the numeric forms of
332 A required field specifier, being one of the following:
333 .Bl -tag -width indent
342 File type and permissions.
344 Number of hard links to
347 User ID and group ID of
351 Device number for character and block device special files.
355 was last accessed or modified, of when the inode was last changed, or
356 the birth time of the inode.
362 Number of blocks allocated for
365 Optimal file system I/O operation block size.
367 User defined flags for
370 Inode generation number.
373 The following four field specifiers are not drawn directly from the
377 .Bl -tag -width indent
379 The name of the file.
381 The file type, either as in
383 or in a more descriptive form if the
389 The target of a symbolic link.
395 field for character or block
396 special devices and gives size output for all others.
402 and the field specifier are required.
403 Most field specifiers default to
405 as an output form, with the
422 .Ex -std stat readlink
424 Given a symbolic link
433 .Bd -literal -offset indent
434 \*[Gt] stat -F /tmp/foo
435 lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] /
437 \*[Gt] stat -LF /tmp/foo
438 drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
441 To initialize some shell variables, you could use the
444 .Bd -literal -offset indent
446 % eval set `stat -s .cshrc`
447 % echo $st_size $st_mtimespec
451 $ eval $(stat -s .profile)
452 $ echo $st_size $st_mtimespec
456 In order to get a list of file types including files pointed to if the
457 file is a symbolic link, you could use the following format:
458 .Bd -literal -offset indent
459 $ stat -f "%N: %HT%SY" /tmp/*
460 /tmp/bar: Symbolic Link -\*[Gt] /tmp/foo
461 /tmp/output25568: Regular File
463 /tmp/foo: Symbolic Link -\*[Gt] /
466 In order to get a list of the devices, their types and the major and minor
467 device numbers, formatted with tabs and linebreaks, you could use the
469 .Bd -literal -offset indent
470 stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
478 Type: Character Device
483 In order to determine the permissions set on a file separately, you could use
484 the following format:
485 .Bd -literal -offset indent
486 \*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" .
487 drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x
490 In order to determine the three files that have been modified most recently,
491 you could use the following format:
492 .Bd -literal -offset indent
493 \*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
494 Apr 25 11:47:00 2002 /tmp/blah
495 Apr 25 10:36:34 2002 /tmp/bar
496 Apr 24 16:47:35 2002 /tmp/foo
499 To display a file's modification time:
500 .Bd -literal -offset indent
501 \*[Gt] stat -f %m /tmp/foo
505 To display the same modification time in a readable format:
506 .Bd -literal -offset indent
507 \*[Gt] stat -f %Sm /tmp/foo
511 To display the same modification time in a readable and sortable format:
512 .Bd -literal -offset indent
513 \*[Gt] stat -f %Sm -t %Y%m%d%H%M%S /tmp/foo
517 To display the same in UTC:
518 .Bd -literal -offset indent
520 $ TZ= stat -f %Sm -t %Y%m%d%H%M%S /tmp/foo
542 utility was written by
544 .Aq atatat@NetBSD.org .
545 This man page was written by
547 .Aq jschauma@NetBSD.org .