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