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