Annotation of src/usr.bin/stat/stat.1, Revision 1.14
1.14 ! espie 1: .\" $OpenBSD: stat.1,v 1.13 2007/11/05 14:49:59 jmc 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: .\"
1.14 ! espie 38: .Dd $Mdocdate: November 5 2007 $
1.1 otto 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.
1.14 ! espie 68: The default format displays the
! 69: .Fa st_dev ,
! 70: .Fa st_ino ,
! 71: .Fa st_mode ,
! 72: .Fa st_nlink ,
! 73: .Fa st_uid ,
! 74: .Fa st_gid ,
! 75: .Fa st_rdev ,
! 76: .Fa st_size ,
! 77: .Fa st_atime ,
! 78: .Fa st_mtime ,
! 79: .Fa st_ctime ,
! 80: .Fa st_blksize ,
! 81: .Fa st_blocks ,
! 82: and
! 83: .Fa st_flags
! 84: fields, in that order.
1.1 otto 85: .Pp
86: The options are as follows:
87: .Bl -tag -width Ds
88: .It Fl F
89: As in
1.2 jmc 90: .Xr ls 1 ,
1.1 otto 91: display a slash (/) immediately after each pathname that is a directory, an
92: asterisk (*) after each that is executable, an at sign (@) after each symbolic
1.10 millert 93: link, an equal sign (=) after each socket, and a vertical bar (|) after each
94: that is a FIFO.
1.1 otto 95: The use of
96: .Fl F
97: implies
98: .Fl l .
1.2 jmc 99: .It Fl f Ar format
100: Display information using the specified format.
1.4 jmc 101: See the
102: .Sx FORMATS
103: section for a description of valid formats.
1.1 otto 104: .It Fl L
105: Use
106: .Xr stat 2
107: instead of
108: .Xr lstat 2 .
109: The information reported by
110: .Nm
111: will refer to the target of
112: .Ar file ,
113: if file is a symbolic link, and not to
114: .Ar file
115: itself.
1.2 jmc 116: .It Fl l
117: Display output in
118: .Ic ls Fl lT
119: format.
1.1 otto 120: .It Fl n
121: Do not force a newline to appear at the end of each piece of output.
122: .It Fl q
123: Suppress failure messages if calls to
124: .Xr stat 2
125: or
126: .Xr lstat 2
127: fail.
128: .It Fl r
129: Display raw information.
130: That is, for all the fields in the stat-structure,
131: display the raw, numerical value (for example, times in seconds since the
1.2 jmc 132: Epoch, etc.).
1.1 otto 133: .It Fl s
134: Display information in ``shell output'', suitable for initializing variables.
135: .It Fl t Ar timefmt
136: Display timestamps using the specified format.
137: This format is
138: passed directly to
139: .Xr strftime 3 .
1.2 jmc 140: .It Fl x
1.4 jmc 141: Display information in a more verbose way.
1.1 otto 142: .El
143: .Ss FORMATS
144: Format strings are similar to
145: .Xr printf 3
146: formats in that they start with
147: .Cm % ,
148: are then followed by a sequence of formatting characters, and end in
149: a character that selects the field of the struct stat which is to be
150: formatted.
151: If the
152: .Cm %
153: is immediately followed by one of
154: .Cm n ,
155: .Cm t ,
156: .Cm % ,
157: or
158: .Cm @ ,
159: then a newline character, a tab character, a percent character,
160: or the current file number is printed, otherwise the string is
161: examined for the following:
162: .Pp
163: Any of the following optional flags:
164: .Bl -tag -width Ds
165: .It Cm #
166: Selects an alternate output form for octal and hexadecimal output.
167: Non-zero octal output will have a leading zero, and non-zero
168: hexadecimal output will have ``0x'' prepended to it.
169: .It Cm +
170: Asserts that a sign indicating whether a number is positive or negative
171: should always be printed.
172: Non-negative numbers are not usually printed
173: with a sign.
174: .It Cm -
175: Aligns string output to the left of the field, instead of to the right.
176: .It Cm 0
177: Sets the fill character for left padding to the 0 character, instead of
178: a space.
179: .It space
180: Reserves a space at the front of non-negative signed output fields.
181: A
182: .Sq Cm +
183: overrides a space if both are used.
184: .El
185: .Pp
186: Then the following fields:
187: .Bl -tag -width Ds
188: .It Cm size
189: An optional decimal digit string specifying the minimum field width.
190: .It Cm prec
191: An optional precision composed of a decimal point
192: .Sq Cm \&.
193: and a decimal digit string that indicates the maximum string length,
194: the number of digits to appear after the decimal point in floating point
195: output, or the minimum number of digits to appear in numeric output.
196: .It Cm fmt
197: An optional output format specifier which is one of
198: .Cm D ,
199: .Cm O ,
200: .Cm U ,
201: .Cm X ,
202: .Cm F ,
203: or
204: .Cm S .
205: These represent signed decimal output, octal output, unsigned decimal
206: output, hexadecimal output, floating point output, and string output,
207: respectively.
208: Some output formats do not apply to all fields.
209: Floating point output only applies to timespec fields (the
210: .Cm a ,
211: .Cm m ,
212: and
213: .Cm c
214: fields).
215: .Pp
216: The special output specifier
217: .Cm S
218: may be used to indicate that the output, if
219: applicable, should be in string format.
220: May be used in combination with
221: .Bl -tag -width Ds
222: .It Cm amc
223: Display date in strftime(3) format.
224: .It Cm dr
225: Display actual device name.
226: .It Cm gu
227: Display group or user name.
228: .It Cm p
229: Display the mode of
230: .Ar file
231: as in
232: .Ic ls -lTd .
233: .It Cm N
234: Displays the name of
235: .Ar file .
236: .It Cm T
237: Displays the type of
238: .Ar file .
239: .It Cm Y
1.2 jmc 240: Insert a `` -\*(Gt '' into the output.
1.1 otto 241: Note that the default output format
242: for
243: .Cm Y
244: is a string, but if specified explicitly, these four characters are
245: prepended.
246: .El
247: .It Cm sub
248: An optional sub field specifier (high, middle, low).
249: Only applies to
250: the
251: .Cm p ,
252: .Cm d ,
253: .Cm r ,
254: and
255: .Cm T
256: output formats.
257: It can be one of the following:
258: .Bl -tag -width Ds
259: .It Cm H
260: ``High'' -- specifies the major number for devices from
261: .Cm r
262: or
263: .Cm d ,
264: the ``user'' bits for permissions from the string form of
265: .Cm p ,
266: the file ``type'' bits from the numeric forms of
267: .Cm p ,
268: and the long output form of
269: .Cm T .
270: .It Cm L
271: ``Low'' -- specifies the minor number for devices from
272: .Cm r
273: or
274: .Cm d ,
275: the ``other'' bits for permissions from the string form of
276: .Cm p ,
277: the ``user'', ``group'', and ``other'' bits from the numeric forms of
278: .Cm p ,
279: and the
280: .Ic ls -F
281: style output character for file type when used with
282: .Cm T
283: (the use of
284: .Cm L
285: for this is optional).
286: .It Cm M
287: ``Middle'' -- specifies the ``group'' bits for permissions from the
288: string output form of
289: .Cm p ,
290: or the ``suid'', ``sgid'', and ``sticky'' bits for the numeric forms of
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
! 325: .Pq Fa st_atimespec , st_mtimespec , st_ctimespec .
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
362: Expands to ``major,minor'' from the rdev field for character or block
363: special devices and gives size output for all others.
364: .El
365: .El
366: .Pp
367: Only the
368: .Cm %
369: and the field specifier are required.
370: Most field specifiers default to
371: .Cm U
372: as an output form, with the
373: exception of
374: .Cm p
375: which defaults to
1.13 jmc 376: .Cm O ;
1.1 otto 377: .Cm a , m ,
378: and
379: .Cm c
380: which default to
1.13 jmc 381: .Cm D ;
1.1 otto 382: and
383: .Cm Y , T ,
384: and
385: .Cm N ,
386: which default to
387: .Cm S .
1.2 jmc 388: .Pp
1.1 otto 389: .Nm
1.2 jmc 390: exits 0 on success, and \*(Gt0 if an error occurred.
1.1 otto 391: .Sh EXAMPLES
392: Given a symbolic link ``foo'' that points from /tmp/foo to /, you would use
393: .Nm
394: as follows:
395: .Bd -literal -offset indent
1.2 jmc 396: \*(Gt stat -F /tmp/foo
397: lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*(Gt /
1.1 otto 398:
1.2 jmc 399: \*(Gt stat -LF /tmp/foo
1.1 otto 400: drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
401: .Ed
402: .Pp
403: To initialize some shell-variables, you could use the
404: .Fl s
405: flag as follows:
406: .Bd -literal -offset indent
1.2 jmc 407: \*(Gt csh
1.1 otto 408: % eval set `stat -s .cshrc`
409: % echo $st_size $st_mtimespec
410: 1148 1015432481
411:
1.2 jmc 412: \*(Gt sh
1.1 otto 413: $ eval $(stat -s .profile)
414: $ echo $st_size $st_mtimespec
415: 1148 1015432481
416: .Ed
417: .Pp
418: In order to get a list of the kind of files including files pointed to if the
419: file is a symbolic link, you could use the following format:
420: .Bd -literal -offset indent
421: $ stat -f "%N: %HT%SY" /tmp/*
1.2 jmc 422: /tmp/bar: Symbolic Link -\*(Gt /tmp/foo
1.1 otto 423: /tmp/output25568: Regular File
424: /tmp/blah: Directory
1.2 jmc 425: /tmp/foo: Symbolic Link -\*(Gt /
1.1 otto 426: .Ed
427: .Pp
428: In order to get a list of the devices, their types and the major and minor
429: device numbers, formatted with tabs and linebreaks, you could use the
430: following format:
1.2 jmc 431: .Bd -literal -offset 4n
1.1 otto 432: stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
433: [...]
1.5 jmc 434: Name: /dev/xfs0
435: Type: Character Device
436: Major: 51
437: Minor: 0
1.1 otto 438:
439: Name: /dev/zero
440: Type: Character Device
441: Major: 2
442: Minor: 12
443: .Ed
444: .Pp
445: In order to determine the permissions set on a file separately, you could use
446: the following format:
447: .Bd -literal -offset indent
1.2 jmc 448: \*(Gt stat -f "%Sp -\*(Gt owner=%SHp group=%SMp other=%SLp" .
449: drwxr-xr-x -\*(Gt owner=rwx group=r-x other=r-x
1.1 otto 450: .Ed
451: .Pp
452: In order to determine the three files that have been modified most recently,
453: you could use the following format:
454: .Bd -literal -offset indent
1.2 jmc 455: \*(Gt stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
1.1 otto 456: Apr 25 11:47:00 2002 /tmp/blah
457: Apr 25 10:36:34 2002 /tmp/bar
458: Apr 24 16:47:35 2002 /tmp/foo
459: .Ed
460: .Sh SEE ALSO
461: .Xr file 1 ,
462: .Xr ls 1 ,
1.8 jmc 463: .Xr readlink 1 ,
1.1 otto 464: .Xr lstat 2 ,
465: .Xr readlink 2 ,
466: .Xr stat 2 ,
467: .Xr printf 3 ,
468: .Xr strftime 3
469: .Sh HISTORY
470: The
471: .Nm
1.6 jmc 472: utility first appeared in
473: .Ox 3.8 .
1.1 otto 474: .Sh AUTHORS
1.11 jaredy 475: .An -nosplit
1.1 otto 476: The
477: .Nm
478: utility was written by
1.2 jmc 479: .An Andrew Brown Aq atatat@NetBSD.org .
1.1 otto 480: This man page was written by
1.2 jmc 481: .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