Annotation of src/usr.bin/stat/stat.1, Revision 1.19
1.19 ! sobrado 1: .\" $OpenBSD: stat.1,v 1.18 2009/01/19 09:46:59 sobrado 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.19 ! sobrado 31: .Dd $Mdocdate: January 19 2009 $
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
127: Display information in ``shell output'', suitable for initializing variables.
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
161: hexadecimal output will have ``0x'' prepended to it.
162: .It Cm +
163: Asserts that a sign indicating whether a number is positive or negative
164: should always be printed.
165: Non-negative numbers are not usually printed
166: with a sign.
167: .It Cm -
168: Aligns string output to the left of the field, instead of to the right.
169: .It Cm 0
170: Sets the fill character for left padding to the 0 character, instead of
171: a space.
172: .It space
173: Reserves a space at the front of non-negative signed output fields.
174: A
175: .Sq Cm +
176: overrides a space if both are used.
177: .El
178: .Pp
179: Then the following fields:
180: .Bl -tag -width Ds
181: .It Cm size
182: An optional decimal digit string specifying the minimum field width.
183: .It Cm prec
184: An optional precision composed of a decimal point
185: .Sq Cm \&.
186: and a decimal digit string that indicates the maximum string length,
187: the number of digits to appear after the decimal point in floating point
188: output, or the minimum number of digits to appear in numeric output.
189: .It Cm fmt
190: An optional output format specifier which is one of
191: .Cm D ,
192: .Cm O ,
193: .Cm U ,
194: .Cm X ,
195: .Cm F ,
196: or
197: .Cm S .
198: These represent signed decimal output, octal output, unsigned decimal
199: output, hexadecimal output, floating point output, and string output,
200: respectively.
201: Some output formats do not apply to all fields.
202: Floating point output only applies to timespec fields (the
203: .Cm a ,
204: .Cm m ,
205: and
206: .Cm c
207: fields).
208: .Pp
209: The special output specifier
210: .Cm S
211: may be used to indicate that the output, if
212: applicable, should be in string format.
213: May be used in combination with
214: .Bl -tag -width Ds
215: .It Cm amc
1.19 ! sobrado 216: Display date in
! 217: .Xr strftime 3
! 218: format.
1.1 otto 219: .It Cm dr
220: Display actual device name.
221: .It Cm gu
222: Display group or user name.
223: .It Cm p
224: Display the mode of
225: .Ar file
226: as in
227: .Ic ls -lTd .
228: .It Cm N
229: Displays the name of
230: .Ar file .
231: .It Cm T
232: Displays the type of
233: .Ar file .
234: .It Cm Y
1.2 jmc 235: Insert a `` -\*(Gt '' into the output.
1.1 otto 236: Note that the default output format
237: for
238: .Cm Y
239: is a string, but if specified explicitly, these four characters are
240: prepended.
241: .El
242: .It Cm sub
243: An optional sub field specifier (high, middle, low).
244: Only applies to
245: the
246: .Cm p ,
247: .Cm d ,
248: .Cm r ,
249: and
250: .Cm T
251: output formats.
252: It can be one of the following:
253: .Bl -tag -width Ds
254: .It Cm H
255: ``High'' -- specifies the major number for devices from
256: .Cm r
257: or
258: .Cm d ,
259: the ``user'' bits for permissions from the string form of
260: .Cm p ,
261: the file ``type'' bits from the numeric forms of
262: .Cm p ,
263: and the long output form of
264: .Cm T .
265: .It Cm L
266: ``Low'' -- specifies the minor number for devices from
267: .Cm r
268: or
269: .Cm d ,
270: the ``other'' bits for permissions from the string form of
271: .Cm p ,
272: the ``user'', ``group'', and ``other'' bits from the numeric forms of
273: .Cm p ,
274: and the
275: .Ic ls -F
276: style output character for file type when used with
277: .Cm T
278: (the use of
279: .Cm L
280: for this is optional).
281: .It Cm M
282: ``Middle'' -- specifies the ``group'' bits for permissions from the
283: string output form of
284: .Cm p ,
285: or the ``suid'', ``sgid'', and ``sticky'' bits for the numeric forms of
286: .Cm p .
287: .El
288: .It Cm datum
289: A required field specifier, being one of the following:
290: .Bl -tag -width Ds
291: .It Cm d
292: Device upon which
293: .Ar file
1.14 espie 294: resides
295: .Pq Fa st_dev .
1.1 otto 296: .It Cm i
1.2 jmc 297: .Ar file Ns 's
1.14 espie 298: inode number
299: .Pq Fa st_ino .
1.1 otto 300: .It Cm p
1.14 espie 301: File type and permissions
302: .Pq Fa st_mode .
1.1 otto 303: .It Cm l
304: Number of hard links to
1.14 espie 305: .Ar file
306: .Pq Fa st_nlink .
1.1 otto 307: .It Cm u , g
308: User-id and group-id of
1.2 jmc 309: .Ar file Ns 's
1.14 espie 310: owner
311: .Pq Fa st_uid , st_gid .
1.1 otto 312: .It Cm r
1.14 espie 313: Device number for character and block device special files
314: .Pq Fa st_rdev .
1.3 otto 315: .It Cm a , m , c , B
1.1 otto 316: The time
317: .Ar file
1.3 otto 318: was last accessed or modified, or when the inode was last changed, or
1.14 espie 319: the birth time of the inode
1.17 jmc 320: .Pq Fa st_atime , st_mtime , st_ctime , st_birthtime .
1.9 otto 321: If the file system does not support birth time, the value is undefined.
1.1 otto 322: .It Cm z
323: The size of
324: .Ar file
1.14 espie 325: in bytes
326: .Pq Fa st_size .
1.1 otto 327: .It Cm b
328: Number of blocks allocated for
1.14 espie 329: .Ar file
330: .Pq Fa st_blocks .
1.1 otto 331: .It Cm k
1.14 espie 332: Optimal file system I/O operation block size
333: .Pq Fa st_blksize .
1.1 otto 334: .It Cm f
335: User defined flags for
1.14 espie 336: .Ar file
337: .Pq Fa st_flags .
1.1 otto 338: .It Cm v
1.14 espie 339: Inode generation number
340: .Pq Fa st_gen .
1.1 otto 341: .El
342: .Pp
343: The following four field specifiers are not drawn directly from the
1.2 jmc 344: data in struct stat, but are:
1.1 otto 345: .Bl -tag -width Ds
346: .It Cm N
347: The name of the file.
348: .It Cm T
349: The file type, either as in
350: .Ic ls -F
351: or in a more descriptive form if the sub field specifier
352: .Cm H
353: is given.
354: .It Cm Y
355: The target of a symbolic link.
356: .It Cm Z
357: Expands to ``major,minor'' from the rdev field for character or block
358: special devices and gives size output for all others.
359: .El
360: .El
361: .Pp
362: Only the
363: .Cm %
364: and the field specifier are required.
365: Most field specifiers default to
366: .Cm U
367: as an output form, with the
368: exception of
369: .Cm p
370: which defaults to
1.13 jmc 371: .Cm O ;
1.1 otto 372: .Cm a , m ,
373: and
374: .Cm c
375: which default to
1.13 jmc 376: .Cm D ;
1.1 otto 377: and
378: .Cm Y , T ,
379: and
380: .Cm N ,
381: which default to
382: .Cm S .
1.2 jmc 383: .Pp
1.18 sobrado 384: .Ex -std stat
1.1 otto 385: .Sh EXAMPLES
386: Given a symbolic link ``foo'' that points from /tmp/foo to /, you would use
387: .Nm
388: as follows:
389: .Bd -literal -offset indent
1.2 jmc 390: \*(Gt stat -F /tmp/foo
391: lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*(Gt /
1.1 otto 392:
1.2 jmc 393: \*(Gt stat -LF /tmp/foo
1.1 otto 394: drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
395: .Ed
396: .Pp
397: To initialize some shell-variables, you could use the
398: .Fl s
399: flag as follows:
400: .Bd -literal -offset indent
1.2 jmc 401: \*(Gt csh
1.1 otto 402: % eval set `stat -s .cshrc`
1.16 todd 403: % echo $st_size $st_mtime
1.1 otto 404: 1148 1015432481
405:
1.2 jmc 406: \*(Gt sh
1.1 otto 407: $ eval $(stat -s .profile)
1.16 todd 408: $ echo $st_size $st_mtime
1.1 otto 409: 1148 1015432481
410: .Ed
411: .Pp
412: In order to get a list of the kind of files including files pointed to if the
413: file is a symbolic link, you could use the following format:
414: .Bd -literal -offset indent
415: $ stat -f "%N: %HT%SY" /tmp/*
1.2 jmc 416: /tmp/bar: Symbolic Link -\*(Gt /tmp/foo
1.1 otto 417: /tmp/output25568: Regular File
418: /tmp/blah: Directory
1.2 jmc 419: /tmp/foo: Symbolic Link -\*(Gt /
1.1 otto 420: .Ed
421: .Pp
422: In order to get a list of the devices, their types and the major and minor
423: device numbers, formatted with tabs and linebreaks, you could use the
424: following format:
1.2 jmc 425: .Bd -literal -offset 4n
1.1 otto 426: stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
427: [...]
1.5 jmc 428: Name: /dev/xfs0
429: Type: Character Device
430: Major: 51
431: Minor: 0
1.1 otto 432:
433: Name: /dev/zero
434: Type: Character Device
435: Major: 2
436: Minor: 12
437: .Ed
438: .Pp
439: In order to determine the permissions set on a file separately, you could use
440: the following format:
441: .Bd -literal -offset indent
1.2 jmc 442: \*(Gt stat -f "%Sp -\*(Gt owner=%SHp group=%SMp other=%SLp" .
443: drwxr-xr-x -\*(Gt owner=rwx group=r-x other=r-x
1.1 otto 444: .Ed
445: .Pp
446: In order to determine the three files that have been modified most recently,
447: you could use the following format:
448: .Bd -literal -offset indent
1.2 jmc 449: \*(Gt stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
1.1 otto 450: Apr 25 11:47:00 2002 /tmp/blah
451: Apr 25 10:36:34 2002 /tmp/bar
452: Apr 24 16:47:35 2002 /tmp/foo
453: .Ed
454: .Sh SEE ALSO
455: .Xr file 1 ,
456: .Xr ls 1 ,
1.8 jmc 457: .Xr readlink 1 ,
1.1 otto 458: .Xr lstat 2 ,
459: .Xr readlink 2 ,
460: .Xr stat 2 ,
461: .Xr printf 3 ,
462: .Xr strftime 3
463: .Sh HISTORY
464: The
465: .Nm
1.6 jmc 466: utility first appeared in
467: .Ox 3.8 .
1.1 otto 468: .Sh AUTHORS
1.11 jaredy 469: .An -nosplit
1.1 otto 470: The
471: .Nm
472: utility was written by
1.2 jmc 473: .An Andrew Brown Aq atatat@NetBSD.org .
1.1 otto 474: This man page was written by
1.2 jmc 475: .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