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