Annotation of src/usr.bin/stat/stat.1, Revision 1.22
1.22 ! bentley 1: .\" $OpenBSD: stat.1,v 1.21 2013/07/16 00:07:52 schwarze Exp $
1.1 otto 2: .\" $NetBSD: stat.1,v 1.11 2003/05/08 13:07:10 wiz Exp $
3: .\"
4: .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
5: .\" All rights reserved.
6: .\"
7: .\" This code is derived from software contributed to The NetBSD Foundation
8: .\" by Andrew Brown and Jan Schaumann.
9: .\"
10: .\" Redistribution and use in source and binary forms, with or without
11: .\" modification, are permitted provided that the following conditions
12: .\" are met:
13: .\" 1. Redistributions of source code must retain the above copyright
14: .\" notice, this list of conditions and the following disclaimer.
15: .\" 2. Redistributions in binary form must reproduce the above copyright
16: .\" notice, this list of conditions and the following disclaimer in the
17: .\" documentation and/or other materials provided with the distribution.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
20: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
23: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29: .\" POSSIBILITY OF SUCH DAMAGE.
30: .\"
1.22 ! bentley 31: .Dd $Mdocdate: July 16 2013 $
1.1 otto 32: .Dt STAT 1
33: .Os
34: .Sh NAME
1.7 deraadt 35: .Nm stat
1.1 otto 36: .Nd display file status
37: .Sh SYNOPSIS
38: .Nm
39: .Op Fl FLnq
40: .Oo
41: .Fl f Ar format |
1.2 jmc 42: .Fl l | r | s | x
1.1 otto 43: .Oc
44: .Op Fl t Ar timefmt
45: .Op Ar
46: .Sh DESCRIPTION
47: The
48: .Nm
49: utility displays information about the file pointed to by
50: .Ar file .
1.2 jmc 51: Read, write, or execute permissions of the named file are not required, but
52: all directories listed in the pathname leading to the file must be
1.1 otto 53: searchable.
54: If no argument is given,
55: .Nm
56: displays information about the file descriptor for standard input.
57: .Pp
58: The information displayed is obtained by calling
59: .Xr lstat 2
60: with the given argument and evaluating the returned structure.
1.14 espie 61: The default format displays the
62: .Fa st_dev ,
63: .Fa st_ino ,
64: .Fa st_mode ,
65: .Fa st_nlink ,
66: .Fa st_uid ,
67: .Fa st_gid ,
68: .Fa st_rdev ,
69: .Fa st_size ,
70: .Fa st_atime ,
71: .Fa st_mtime ,
72: .Fa st_ctime ,
73: .Fa st_blksize ,
74: .Fa st_blocks ,
75: and
76: .Fa st_flags
77: fields, in that order.
1.1 otto 78: .Pp
79: The options are as follows:
80: .Bl -tag -width Ds
81: .It Fl F
82: As in
1.2 jmc 83: .Xr ls 1 ,
1.1 otto 84: display a slash (/) immediately after each pathname that is a directory, an
85: asterisk (*) after each that is executable, an at sign (@) after each symbolic
1.10 millert 86: link, an equal sign (=) after each socket, and a vertical bar (|) after each
87: that is a FIFO.
1.1 otto 88: The use of
89: .Fl F
90: implies
91: .Fl l .
1.2 jmc 92: .It Fl f Ar format
93: Display information using the specified format.
1.4 jmc 94: See the
95: .Sx FORMATS
96: section for a description of valid formats.
1.1 otto 97: .It Fl L
98: Use
99: .Xr stat 2
100: instead of
101: .Xr lstat 2 .
102: The information reported by
103: .Nm
104: will refer to the target of
105: .Ar file ,
106: if file is a symbolic link, and not to
107: .Ar file
108: itself.
1.2 jmc 109: .It Fl l
110: Display output in
111: .Ic ls Fl lT
112: format.
1.1 otto 113: .It Fl n
114: Do not force a newline to appear at the end of each piece of output.
115: .It Fl q
116: Suppress failure messages if calls to
117: .Xr stat 2
118: or
119: .Xr lstat 2
120: fail.
121: .It Fl r
122: Display raw information.
123: That is, for all the fields in the stat-structure,
124: display the raw, numerical value (for example, times in seconds since the
1.2 jmc 125: Epoch, etc.).
1.1 otto 126: .It Fl s
1.22 ! bentley 127: Format the output as a line of shell variable assignments.
1.1 otto 128: .It Fl t Ar timefmt
129: Display timestamps using the specified format.
130: This format is
131: passed directly to
132: .Xr strftime 3 .
1.2 jmc 133: .It Fl x
1.4 jmc 134: Display information in a more verbose way.
1.1 otto 135: .El
136: .Ss FORMATS
137: Format strings are similar to
138: .Xr printf 3
139: formats in that they start with
140: .Cm % ,
141: are then followed by a sequence of formatting characters, and end in
142: a character that selects the field of the struct stat which is to be
143: formatted.
144: If the
145: .Cm %
146: is immediately followed by one of
147: .Cm n ,
148: .Cm t ,
149: .Cm % ,
150: or
151: .Cm @ ,
152: then a newline character, a tab character, a percent character,
153: or the current file number is printed, otherwise the string is
154: examined for the following:
155: .Pp
156: Any of the following optional flags:
157: .Bl -tag -width Ds
158: .It Cm #
159: Selects an alternate output form for octal and hexadecimal output.
160: Non-zero octal output will have a leading zero, and non-zero
1.22 ! bentley 161: hexadecimal output will have
! 162: .Sq 0x
! 163: prepended to it.
1.1 otto 164: .It Cm +
165: Asserts that a sign indicating whether a number is positive or negative
166: should always be printed.
167: Non-negative numbers are not usually printed
168: with a sign.
169: .It Cm -
170: Aligns string output to the left of the field, instead of to the right.
171: .It Cm 0
172: Sets the fill character for left padding to the 0 character, instead of
173: a space.
174: .It space
175: Reserves a space at the front of non-negative signed output fields.
176: A
177: .Sq Cm +
178: overrides a space if both are used.
179: .El
180: .Pp
181: Then the following fields:
182: .Bl -tag -width Ds
183: .It Cm size
184: An optional decimal digit string specifying the minimum field width.
185: .It Cm prec
186: An optional precision composed of a decimal point
187: .Sq Cm \&.
188: and a decimal digit string that indicates the maximum string length,
189: the number of digits to appear after the decimal point in floating point
190: output, or the minimum number of digits to appear in numeric output.
191: .It Cm fmt
192: An optional output format specifier which is one of
193: .Cm D ,
194: .Cm O ,
195: .Cm U ,
196: .Cm X ,
197: .Cm F ,
198: or
199: .Cm S .
200: These represent signed decimal output, octal output, unsigned decimal
201: output, hexadecimal output, floating point output, and string output,
202: respectively.
203: Some output formats do not apply to all fields.
204: Floating point output only applies to timespec fields (the
205: .Cm a ,
206: .Cm m ,
207: and
208: .Cm c
209: fields).
210: .Pp
211: The special output specifier
212: .Cm S
213: may be used to indicate that the output, if
214: applicable, should be in string format.
215: May be used in combination with
216: .Bl -tag -width Ds
217: .It Cm amc
1.19 sobrado 218: Display date in
219: .Xr strftime 3
220: format.
1.1 otto 221: .It Cm dr
222: Display actual device name.
223: .It Cm gu
224: Display group or user name.
225: .It Cm p
226: Display the mode of
227: .Ar file
228: as in
229: .Ic ls -lTd .
230: .It Cm N
231: Displays the name of
232: .Ar file .
233: .It Cm T
234: Displays the type of
235: .Ar file .
236: .It Cm Y
1.22 ! bentley 237: Insert a
! 238: .Dq "\ ->\ "
! 239: into the output.
1.1 otto 240: Note that the default output format
241: for
242: .Cm Y
243: is a string, but if specified explicitly, these four characters are
244: prepended.
245: .El
246: .It Cm sub
247: An optional sub field specifier (high, middle, low).
248: Only applies to
249: the
250: .Cm p ,
251: .Cm d ,
252: .Cm r ,
253: and
254: .Cm T
255: output formats.
256: It can be one of the following:
257: .Bl -tag -width Ds
258: .It Cm H
1.22 ! bentley 259: High -- specifies the major number for devices from
1.1 otto 260: .Cm r
261: or
262: .Cm d ,
1.22 ! bentley 263: the user bits for permissions from the string form of
1.1 otto 264: .Cm p ,
1.22 ! bentley 265: the file type bits from the numeric forms of
1.1 otto 266: .Cm p ,
267: and the long output form of
268: .Cm T .
269: .It Cm L
1.22 ! bentley 270: Low -- specifies the minor number for devices from
1.1 otto 271: .Cm r
272: or
273: .Cm d ,
1.22 ! bentley 274: the other bits for permissions from the string form of
1.1 otto 275: .Cm p ,
1.22 ! bentley 276: the user, group, and other bits from the numeric forms of
1.1 otto 277: .Cm p ,
278: and the
279: .Ic ls -F
280: style output character for file type when used with
281: .Cm T
282: (the use of
283: .Cm L
284: for this is optional).
285: .It Cm M
1.22 ! bentley 286: Middle -- specifies the group bits for permissions from the
1.1 otto 287: string output form of
288: .Cm p ,
1.22 ! bentley 289: or the
! 290: suid, sgid, and sticky bits for the numeric forms of
1.1 otto 291: .Cm p .
292: .El
293: .It Cm datum
294: A required field specifier, being one of the following:
295: .Bl -tag -width Ds
296: .It Cm d
297: Device upon which
298: .Ar file
1.14 espie 299: resides
300: .Pq Fa st_dev .
1.1 otto 301: .It Cm i
1.2 jmc 302: .Ar file Ns 's
1.14 espie 303: inode number
304: .Pq Fa st_ino .
1.1 otto 305: .It Cm p
1.14 espie 306: File type and permissions
307: .Pq Fa st_mode .
1.1 otto 308: .It Cm l
309: Number of hard links to
1.14 espie 310: .Ar file
311: .Pq Fa st_nlink .
1.1 otto 312: .It Cm u , g
313: User-id and group-id of
1.2 jmc 314: .Ar file Ns 's
1.14 espie 315: owner
316: .Pq Fa st_uid , st_gid .
1.1 otto 317: .It Cm r
1.14 espie 318: Device number for character and block device special files
319: .Pq Fa st_rdev .
1.3 otto 320: .It Cm a , m , c , B
1.1 otto 321: The time
322: .Ar file
1.3 otto 323: was last accessed or modified, or when the inode was last changed, or
1.14 espie 324: the birth time of the inode
1.17 jmc 325: .Pq Fa st_atime , st_mtime , st_ctime , st_birthtime .
1.9 otto 326: If the file system does not support birth time, the value is undefined.
1.1 otto 327: .It Cm z
328: The size of
329: .Ar file
1.14 espie 330: in bytes
331: .Pq Fa st_size .
1.1 otto 332: .It Cm b
333: Number of blocks allocated for
1.14 espie 334: .Ar file
335: .Pq Fa st_blocks .
1.1 otto 336: .It Cm k
1.14 espie 337: Optimal file system I/O operation block size
338: .Pq Fa st_blksize .
1.1 otto 339: .It Cm f
340: User defined flags for
1.14 espie 341: .Ar file
342: .Pq Fa st_flags .
1.1 otto 343: .It Cm v
1.14 espie 344: Inode generation number
345: .Pq Fa st_gen .
1.1 otto 346: .El
347: .Pp
348: The following four field specifiers are not drawn directly from the
1.2 jmc 349: data in struct stat, but are:
1.1 otto 350: .Bl -tag -width Ds
351: .It Cm N
352: The name of the file.
353: .It Cm T
354: The file type, either as in
355: .Ic ls -F
356: or in a more descriptive form if the sub field specifier
357: .Cm H
358: is given.
359: .It Cm Y
360: The target of a symbolic link.
361: .It Cm Z
1.22 ! bentley 362: Expands to
! 363: .Ar major , Ns Ar minor
! 364: from the rdev field for character or block
1.1 otto 365: special devices and gives size output for all others.
366: .El
367: .El
368: .Pp
369: Only the
370: .Cm %
371: and the field specifier are required.
372: Most field specifiers default to
373: .Cm U
374: as an output form, with the
375: exception of
376: .Cm p
377: which defaults to
1.13 jmc 378: .Cm O ;
1.1 otto 379: .Cm a , m ,
380: and
381: .Cm c
382: which default to
1.13 jmc 383: .Cm D ;
1.1 otto 384: and
385: .Cm Y , T ,
386: and
387: .Cm N ,
388: which default to
389: .Cm S .
1.20 jmc 390: .Sh EXIT STATUS
1.18 sobrado 391: .Ex -std stat
1.1 otto 392: .Sh EXAMPLES
1.22 ! bentley 393: Given a symbolic link
! 394: .Pa foo
! 395: that points from
! 396: .Pa /tmp/foo
! 397: to
! 398: .Pa / ,
! 399: you would use
1.1 otto 400: .Nm
401: as follows:
402: .Bd -literal -offset indent
1.2 jmc 403: \*(Gt stat -F /tmp/foo
404: lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*(Gt /
1.1 otto 405:
1.2 jmc 406: \*(Gt stat -LF /tmp/foo
1.1 otto 407: drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
408: .Ed
409: .Pp
410: To initialize some shell-variables, you could use the
411: .Fl s
412: flag as follows:
413: .Bd -literal -offset indent
1.2 jmc 414: \*(Gt csh
1.1 otto 415: % eval set `stat -s .cshrc`
1.16 todd 416: % echo $st_size $st_mtime
1.1 otto 417: 1148 1015432481
418:
1.2 jmc 419: \*(Gt sh
1.1 otto 420: $ eval $(stat -s .profile)
1.16 todd 421: $ echo $st_size $st_mtime
1.1 otto 422: 1148 1015432481
423: .Ed
424: .Pp
425: In order to get a list of the kind of files including files pointed to if the
426: file is a symbolic link, you could use the following format:
427: .Bd -literal -offset indent
428: $ stat -f "%N: %HT%SY" /tmp/*
1.2 jmc 429: /tmp/bar: Symbolic Link -\*(Gt /tmp/foo
1.1 otto 430: /tmp/output25568: Regular File
431: /tmp/blah: Directory
1.2 jmc 432: /tmp/foo: Symbolic Link -\*(Gt /
1.1 otto 433: .Ed
434: .Pp
435: In order to get a list of the devices, their types and the major and minor
436: device numbers, formatted with tabs and linebreaks, you could use the
437: following format:
1.2 jmc 438: .Bd -literal -offset 4n
1.1 otto 439: stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
440: [...]
1.5 jmc 441: Name: /dev/xfs0
442: Type: Character Device
443: Major: 51
444: Minor: 0
1.1 otto 445:
446: Name: /dev/zero
447: Type: Character Device
448: Major: 2
449: Minor: 12
450: .Ed
451: .Pp
452: In order to determine the permissions set on a file separately, you could use
453: the following format:
454: .Bd -literal -offset indent
1.2 jmc 455: \*(Gt stat -f "%Sp -\*(Gt owner=%SHp group=%SMp other=%SLp" .
456: drwxr-xr-x -\*(Gt owner=rwx group=r-x other=r-x
1.1 otto 457: .Ed
458: .Pp
459: In order to determine the three files that have been modified most recently,
460: you could use the following format:
461: .Bd -literal -offset indent
1.2 jmc 462: \*(Gt stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
1.1 otto 463: Apr 25 11:47:00 2002 /tmp/blah
464: Apr 25 10:36:34 2002 /tmp/bar
465: Apr 24 16:47:35 2002 /tmp/foo
466: .Ed
467: .Sh SEE ALSO
468: .Xr file 1 ,
469: .Xr ls 1 ,
1.8 jmc 470: .Xr readlink 1 ,
1.1 otto 471: .Xr lstat 2 ,
472: .Xr readlink 2 ,
473: .Xr stat 2 ,
474: .Xr printf 3 ,
475: .Xr strftime 3
476: .Sh HISTORY
477: The
478: .Nm
1.6 jmc 479: utility first appeared in
480: .Ox 3.8 .
1.1 otto 481: .Sh AUTHORS
1.11 jaredy 482: .An -nosplit
1.1 otto 483: The
484: .Nm
485: utility was written by
1.21 schwarze 486: .An Andrew Brown Aq Mt atatat@NetBSD.org .
1.1 otto 487: This man page was written by
1.21 schwarze 488: .An Jan Schaumann Aq Mt jschauma@NetBSD.org .
![[BACK]](/icons/back.gif){kind=icon}
Return to stat.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / stat