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