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