2.\"
3.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Andrew Brown and Jan Schaumann.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\" must display the following acknowledgement:
19.\" This product includes software developed by the NetBSD
20.\" Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\" contributors may be used to endorse or promote products derived
23.\" from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
| 2.\"
3.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Andrew Brown and Jan Schaumann.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\" must display the following acknowledgement:
19.\" This product includes software developed by the NetBSD
20.\" Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\" contributors may be used to endorse or promote products derived
23.\" from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
|
105.It Fl r
106Display raw information. That is, for all the fields in the stat-structure,
107display the raw, numerical value (for example, times in seconds since the
108epoch, etc.)
109.It Fl s
110Display information in ``shell output'', suitable for initializing variables.
111.It Fl x
112Display information in a more verbose way as known from some Linux
113distributions.
114.It Fl t Ar timefmt
115Display timestamps using the specified format. This format is
116passed directly to
117.Xr strftime 3 .
118.El
119.Ss FORMATS
120Format strings are similar to
121.Xr printf 3
122formats in that they start with
123.Cm % ,
124are then followed by a sequence of formatting characters, and end in
125a character that selects the field of the struct stat which is to be
126formatted. If the
127.Cm %
128is immediately followed by one of
129.Cm n ,
130.Cm t ,
131.Cm % ,
132or
133.Cm @ ,
134then a newline character, a tab character, a percent character,
135or the current file number is printed, otherwise the string is
136examined for the following:
137.Pp
138Any of the following optional flags:
139.Bl -tag -width Ds
140.It Cm #
141Selects an alternate output form for octal and hexadecimal output.
142Non-zero octal output will have a leading zero, and non-zero
143hexadecimal output will have ``0x'' prepended to it.
144.It Cm +
145Asserts that a sign indicating whether a number is positive or negative
146should always be printed. Non-negative numbers are not usually printed
147with a sign.
148.It Cm -
149Aligns string output to the left of the field, instead of to the right.
150.It Cm 0
151Sets the fill character for left padding to the 0 character, instead of
152a space.
153.It space
154Reserves a space at the front of non-negative signed output fields. A
155.Sq Cm +
156overrides a space if both are used.
157.El
158.Pp
159Then the following fields:
160.Bl -tag -width Ds
161.It Cm size
162An optional decimal digit string specifying the minimum field width.
163.It Cm prec
164An optional precision composed of a decimal point
165.Sq Cm \&.
166and a decimal digit string that indicates the maximum string length,
167the number of digits to appear after the decimal point in floating point
168output, or the minimum number of digits to appear in numeric output.
169.It Cm fmt
170An optional output format specifier which is one of
171.Cm D ,
172.Cm O ,
173.Cm U ,
174.Cm X ,
175.Cm F ,
176or
177.Cm S .
178These represent signed decimal output, octal output, unsigned decimal
179output, hexadecimal output, floating point output, and string output,
180respectively. Some output formats do not apply to all fields.
181Floating point output only applies to timespec fields (the
182.Cm a ,
183.Cm m ,
184and
185.Cm c
186fields).
187.Pp
188The special output specifier
189.Cm S
190may be used to indicate that the output, if
191applicable, should be in string format. May be used in combination with
192.Bl -tag -width Ds
193.It Cm amc
194Display date in strftime(3) format.
195.It Cm dr
196Display actual device name.
197.It Cm gu
198Display group or user name.
199.It Cm p
200Display the mode of
201.Ar file
202as in
203.Ic ls -lTd .
204.It Cm N
205Displays the name of
206.Ar file .
207.It Cm T
208Displays the type of
209.Ar file .
210.It Cm Y
211Insert a `` -\*[Gt] '' into the output. Note that the default output format
212for
213.Cm Y
214is a string, but if specified explicitly, these four characters are
215prepended.
216.El
217.It Cm sub
218An optional sub field specifier (high, middle, low). Only applies to
219the
220.Cm p ,
221.Cm d ,
222.Cm r ,
223and
224.Cm T
225output formats. It can be one of the following:
226.Bl -tag -width Ds
227.It Cm H
228``High'' -- specifies the major number for devices from
229.Cm r
230or
231.Cm d ,
232the ``user'' bits for permissions from the string form of
233.Cm p ,
234the file ``type'' bits from the numeric forms of
235.Cm p ,
236and the long output form of
237.Cm T .
238.It Cm L
239``Low'' -- specifies the minor number for devices from
240.Cm r
241or
242.Cm d ,
243the ``other'' bits for permissions from the string form of
244.Cm p ,
245the ``user'', ``group'', and ``other'' bits from the numeric forms of
246.Cm p ,
247and the
248.Ic ls -F
249style output character for file type when used with
250.Cm T
251(the use of
252.Cm L
253for this is optional).
254.It Cm M
255``Middle'' -- specifies the ``group'' bits for permissions from the
256string output form of
257.Cm p ,
258or the ``suid'', ``sgid'', and ``sticky'' bits for the numeric forms of
259.Cm p .
260.El
261.It Cm datum
262A required field specifier, being one of the following:
263.Bl -tag -width Ds
264.It Cm d
265Device upon which
266.Ar file
267resides.
268.It Cm i
269.Ar file Ap s
270inode number.
271.It Cm p
272File type and permissions.
273.It Cm l
274Number of hard links to
275.Ar file .
276.It Cm u , g
277User-id and group-id of
278.Ar file Ap s
279owner.
280.It Cm r
281Device number for character and block device special files.
282.It Cm a , m , c
283The time
284.Ar file
285was last accessed, modified, or of when the inode was last changed.
286.It Cm z
287The size of
288.Ar file
289in bytes.
290.It Cm b
291Number of blocks allocated for
292.Ar file .
293.It Cm k
294Optimal file system I/O operation block size.
295.It Cm f
296User defined flags for
297.Ar file .
298.It Cm v
299Inode generation number.
300.El
301.Pp
302The following four field specifiers are not drawn directly from the
303data in struct stat, but are
304.Bl -tag -width Ds
305.It Cm N
306The name of the file.
307.It Cm T
308The file type, either as in
309.Ic ls -F
310or in a more descriptive form if the sub field specifier
311.Cm H
312is given.
313.It Cm Y
314The target of a symbolic link.
315.It Cm Z
316Expands to ``major,minor'' from the rdev field for character or block
317special devices and gives size output for all others.
318.El
319.El
320.Pp
321Only the
322.Cm %
323and the field specifier are required. Most field
324specifiers default to
325.Cm U
326as an output form, with the
327exception of
328.Cm p
329which defaults to
330.Cm O ,
331.Cm a , m ,
332and
333.Cm c
334which default to
335.Cm D ,
336and
337.Cm Y , T ,
338and
339.Cm N ,
340which default to
341.Cm S .
342.Sh EXIT STATUS
343.Nm
344exits 0 on success, and \*[Gt]0 if an error occurred.
345.Sh EXAMPLES
346Given a symbolic link ``foo'' that points from /tmp/foo to /, you would use
347.Nm
348as follows:
349.Bd -literal -offset indent
350\*[Gt] stat -F /tmp/foo
351lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] /
352
353\*[Gt] stat -LF /tmp/foo
354lrwxrwxrwx 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
355.Ed
356.Pp
357To initialize some shell-variables, you could use the
358.Fl s
359flag as follows:
360.Bd -literal -offset indent
361\*[Gt] csh
362% eval set `stat -s .cshrc`
363% echo $st_size $st_mtimespec
3641148 1015432481
365
366\*[Gt] sh
367$ eval $(stat -s .profile)
368$ echo $st_size $st_mtimespec
3691148 1015432481
370.Ed
371.Pp
372In order to get a list of the kind of files including files pointed to if the
373file is a symbolic link, you could use the following format:
374.Bd -literal -offset indent
375$ stat -f "%N: %HT%SY" /tmp/*
376/tmp/bar: Symbolic Link -\*[Gt] /tmp/foo
377/tmp/output25568: Regular File
378/tmp/blah: Directory
379/tmp/foo: Symbolic Link -\*[Gt] /
380.Ed
381.Pp
382In order to get a list of the devices, their types and the major and minor
383device numbers, formatted with tabs and linebreaks, you could use the
384following format:
385.Bd -literal -offset indent
386stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
387[...]
388Name: /dev/wt8
389 Type: Block Device
390 Major: 3
391 Minor: 8
392
393Name: /dev/zero
394 Type: Character Device
395 Major: 2
396 Minor: 12
397.Ed
398.Pp
399In order to determine the permissions set on a file separately, you could use
400the following format:
401.Bd -literal -offset indent
402\*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" .
403drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x
404.Ed
405.Pp
406In order to determine the three files that have been modified most recently,
407you could use the following format:
408.Bd -literal -offset indent
409\*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
410Apr 25 11:47:00 2002 /tmp/blah
411Apr 25 10:36:34 2002 /tmp/bar
412Apr 24 16:47:35 2002 /tmp/foo
413.Ed
414.Sh SEE ALSO
415.Xr file 1 ,
416.Xr ls 1 ,
417.Xr lstat 2 ,
418.Xr readlink 2 ,
419.Xr stat 2 ,
420.Xr printf 3 ,
421.Xr strftime 3
422.Sh HISTORY
423The
424.Nm
425utility appeared in
426.Nx 1.6 .
427.Sh AUTHORS
428The
429.Nm
430utility was written by Andrew Brown
431.Aq atatat@netbsd.org .
432This man page
433was written by Jan Schaumann
434.Aq jschauma@netbsd.org .
| 120.It Fl r
121Display raw information. That is, for all the fields in the stat-structure,
122display the raw, numerical value (for example, times in seconds since the
123epoch, etc.)
124.It Fl s
125Display information in ``shell output'', suitable for initializing variables.
126.It Fl x
127Display information in a more verbose way as known from some Linux
128distributions.
129.It Fl t Ar timefmt
130Display timestamps using the specified format. This format is
131passed directly to
132.Xr strftime 3 .
133.El
134.Ss FORMATS
135Format strings are similar to
136.Xr printf 3
137formats in that they start with
138.Cm % ,
139are then followed by a sequence of formatting characters, and end in
140a character that selects the field of the struct stat which is to be
141formatted. If the
142.Cm %
143is immediately followed by one of
144.Cm n ,
145.Cm t ,
146.Cm % ,
147or
148.Cm @ ,
149then a newline character, a tab character, a percent character,
150or the current file number is printed, otherwise the string is
151examined for the following:
152.Pp
153Any of the following optional flags:
154.Bl -tag -width Ds
155.It Cm #
156Selects an alternate output form for octal and hexadecimal output.
157Non-zero octal output will have a leading zero, and non-zero
158hexadecimal output will have ``0x'' prepended to it.
159.It Cm +
160Asserts that a sign indicating whether a number is positive or negative
161should always be printed. Non-negative numbers are not usually printed
162with a sign.
163.It Cm -
164Aligns string output to the left of the field, instead of to the right.
165.It Cm 0
166Sets the fill character for left padding to the 0 character, instead of
167a space.
168.It space
169Reserves a space at the front of non-negative signed output fields. A
170.Sq Cm +
171overrides a space if both are used.
172.El
173.Pp
174Then the following fields:
175.Bl -tag -width Ds
176.It Cm size
177An optional decimal digit string specifying the minimum field width.
178.It Cm prec
179An optional precision composed of a decimal point
180.Sq Cm \&.
181and a decimal digit string that indicates the maximum string length,
182the number of digits to appear after the decimal point in floating point
183output, or the minimum number of digits to appear in numeric output.
184.It Cm fmt
185An optional output format specifier which is one of
186.Cm D ,
187.Cm O ,
188.Cm U ,
189.Cm X ,
190.Cm F ,
191or
192.Cm S .
193These represent signed decimal output, octal output, unsigned decimal
194output, hexadecimal output, floating point output, and string output,
195respectively. Some output formats do not apply to all fields.
196Floating point output only applies to timespec fields (the
197.Cm a ,
198.Cm m ,
199and
200.Cm c
201fields).
202.Pp
203The special output specifier
204.Cm S
205may be used to indicate that the output, if
206applicable, should be in string format. May be used in combination with
207.Bl -tag -width Ds
208.It Cm amc
209Display date in strftime(3) format.
210.It Cm dr
211Display actual device name.
212.It Cm gu
213Display group or user name.
214.It Cm p
215Display the mode of
216.Ar file
217as in
218.Ic ls -lTd .
219.It Cm N
220Displays the name of
221.Ar file .
222.It Cm T
223Displays the type of
224.Ar file .
225.It Cm Y
226Insert a `` -\*[Gt] '' into the output. Note that the default output format
227for
228.Cm Y
229is a string, but if specified explicitly, these four characters are
230prepended.
231.El
232.It Cm sub
233An optional sub field specifier (high, middle, low). Only applies to
234the
235.Cm p ,
236.Cm d ,
237.Cm r ,
238and
239.Cm T
240output formats. It can be one of the following:
241.Bl -tag -width Ds
242.It Cm H
243``High'' -- specifies the major number for devices from
244.Cm r
245or
246.Cm d ,
247the ``user'' bits for permissions from the string form of
248.Cm p ,
249the file ``type'' bits from the numeric forms of
250.Cm p ,
251and the long output form of
252.Cm T .
253.It Cm L
254``Low'' -- specifies the minor number for devices from
255.Cm r
256or
257.Cm d ,
258the ``other'' bits for permissions from the string form of
259.Cm p ,
260the ``user'', ``group'', and ``other'' bits from the numeric forms of
261.Cm p ,
262and the
263.Ic ls -F
264style output character for file type when used with
265.Cm T
266(the use of
267.Cm L
268for this is optional).
269.It Cm M
270``Middle'' -- specifies the ``group'' bits for permissions from the
271string output form of
272.Cm p ,
273or the ``suid'', ``sgid'', and ``sticky'' bits for the numeric forms of
274.Cm p .
275.El
276.It Cm datum
277A required field specifier, being one of the following:
278.Bl -tag -width Ds
279.It Cm d
280Device upon which
281.Ar file
282resides.
283.It Cm i
284.Ar file Ap s
285inode number.
286.It Cm p
287File type and permissions.
288.It Cm l
289Number of hard links to
290.Ar file .
291.It Cm u , g
292User-id and group-id of
293.Ar file Ap s
294owner.
295.It Cm r
296Device number for character and block device special files.
297.It Cm a , m , c
298The time
299.Ar file
300was last accessed, modified, or of when the inode was last changed.
301.It Cm z
302The size of
303.Ar file
304in bytes.
305.It Cm b
306Number of blocks allocated for
307.Ar file .
308.It Cm k
309Optimal file system I/O operation block size.
310.It Cm f
311User defined flags for
312.Ar file .
313.It Cm v
314Inode generation number.
315.El
316.Pp
317The following four field specifiers are not drawn directly from the
318data in struct stat, but are
319.Bl -tag -width Ds
320.It Cm N
321The name of the file.
322.It Cm T
323The file type, either as in
324.Ic ls -F
325or in a more descriptive form if the sub field specifier
326.Cm H
327is given.
328.It Cm Y
329The target of a symbolic link.
330.It Cm Z
331Expands to ``major,minor'' from the rdev field for character or block
332special devices and gives size output for all others.
333.El
334.El
335.Pp
336Only the
337.Cm %
338and the field specifier are required. Most field
339specifiers default to
340.Cm U
341as an output form, with the
342exception of
343.Cm p
344which defaults to
345.Cm O ,
346.Cm a , m ,
347and
348.Cm c
349which default to
350.Cm D ,
351and
352.Cm Y , T ,
353and
354.Cm N ,
355which default to
356.Cm S .
357.Sh EXIT STATUS
358.Nm
359exits 0 on success, and \*[Gt]0 if an error occurred.
360.Sh EXAMPLES
361Given a symbolic link ``foo'' that points from /tmp/foo to /, you would use
362.Nm
363as follows:
364.Bd -literal -offset indent
365\*[Gt] stat -F /tmp/foo
366lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] /
367
368\*[Gt] stat -LF /tmp/foo
369lrwxrwxrwx 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
370.Ed
371.Pp
372To initialize some shell-variables, you could use the
373.Fl s
374flag as follows:
375.Bd -literal -offset indent
376\*[Gt] csh
377% eval set `stat -s .cshrc`
378% echo $st_size $st_mtimespec
3791148 1015432481
380
381\*[Gt] sh
382$ eval $(stat -s .profile)
383$ echo $st_size $st_mtimespec
3841148 1015432481
385.Ed
386.Pp
387In order to get a list of the kind of files including files pointed to if the
388file is a symbolic link, you could use the following format:
389.Bd -literal -offset indent
390$ stat -f "%N: %HT%SY" /tmp/*
391/tmp/bar: Symbolic Link -\*[Gt] /tmp/foo
392/tmp/output25568: Regular File
393/tmp/blah: Directory
394/tmp/foo: Symbolic Link -\*[Gt] /
395.Ed
396.Pp
397In order to get a list of the devices, their types and the major and minor
398device numbers, formatted with tabs and linebreaks, you could use the
399following format:
400.Bd -literal -offset indent
401stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
402[...]
403Name: /dev/wt8
404 Type: Block Device
405 Major: 3
406 Minor: 8
407
408Name: /dev/zero
409 Type: Character Device
410 Major: 2
411 Minor: 12
412.Ed
413.Pp
414In order to determine the permissions set on a file separately, you could use
415the following format:
416.Bd -literal -offset indent
417\*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" .
418drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x
419.Ed
420.Pp
421In order to determine the three files that have been modified most recently,
422you could use the following format:
423.Bd -literal -offset indent
424\*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
425Apr 25 11:47:00 2002 /tmp/blah
426Apr 25 10:36:34 2002 /tmp/bar
427Apr 24 16:47:35 2002 /tmp/foo
428.Ed
429.Sh SEE ALSO
430.Xr file 1 ,
431.Xr ls 1 ,
432.Xr lstat 2 ,
433.Xr readlink 2 ,
434.Xr stat 2 ,
435.Xr printf 3 ,
436.Xr strftime 3
437.Sh HISTORY
438The
439.Nm
440utility appeared in
441.Nx 1.6 .
442.Sh AUTHORS
443The
444.Nm
445utility was written by Andrew Brown
446.Aq atatat@netbsd.org .
447This man page
448was written by Jan Schaumann
449.Aq jschauma@netbsd.org .
|