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