xref: /minix3/usr.bin/stat/stat.1 (revision 0a6a1f1d05b60e214de2f05a7310ddd1f0e590e7)
1.\"	$NetBSD: stat.1,v 1.37 2014/04/13 01:45:34 snj Exp $
2.\"
3.\" Copyright (c) 2002-2011 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 December 2, 2012
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 fnqsv
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_birthtime ,
98.Fa st_blksize ,
99.Fa st_blocks ,
100and
101.Fa st_flags
102fields, in that order.
103.Pp
104The options are as follows:
105.Bl -tag -width XFXformatXXX
106.It Fl F
107As in
108.Xr ls 1 ,
109display a slash
110.Pq Sq /
111immediately after each pathname that is a directory, an
112asterisk
113.Pq Sq *
114after each that is executable, an at sign
115.Pq Sq @
116after each symbolic link, a percent sign
117.Pq Sq %
118after each whiteout, an equal sign
119.Pq Sq =
120after each socket, and a vertical bar
121.Pq Sq \&|
122after each that is a FIFO.
123The use of
124.Fl F
125implies
126.Fl l .
127.It Fl f Ar format
128Display information using the specified format.
129See the
130.Sx FORMATS
131section for a description of valid formats.
132.It Fl L
133Use
134.Xr stat 2
135instead of
136.Xr lstat 2 .
137The information reported by
138.Nm
139will refer to the target of
140.Ar file ,
141if file is a symbolic link, and not to
142.Ar file
143itself.
144.It Fl l
145Display output in
146.Ic ls Fl lT
147format.
148.It Fl n
149Do not force a newline to appear at the end of each piece of output.
150.It Fl q
151Suppress failure messages if calls to
152.Xr stat 2
153or
154.Xr lstat 2
155fail.
156When run as
157.Nm readlink ,
158error messages are automatically suppressed.
159.It Fl r
160Display raw information.
161That is, for all the fields in the stat-structure,
162display the raw, numerical value (for example, times in seconds since the
163epoch, etc.)
164.It Fl s
165Display information in
166.Dq shell output ,
167suitable for initializing variables.
168When run as
169.Nm readlink ,
170suppress error messages.
171This is equivalent to specifying
172.Bd -literal
173FMT="st_dev=%d st_ino=%i st_mode=%#p st_nlink=%l st_uid=%u st_gid=%g"
174FMT="$FMT st_rdev=%r st_size=%z st_atime=%Sa st_mtime=%Sm st_ctime=%Sc"
175FMT="$FMT st_birthtime=%SB st_blksize=%k st_blocks=%b st_flags=%f"
176stat -t %s -f "$FMT" .
177.Ed
178Note that if you use a timeformat that contains embedded whitespace or shell
179meta-characters you will need to include appropriate quoting so the
180.Fl s
181output remains valid.
182.It Fl t Ar timefmt
183Display timestamps using the specified format.
184This format is
185passed directly to
186.Xr strftime 3 .
187.It Fl v
188Turn off quiet mode.
189.It Fl x
190Display information in a more verbose way as known from some Linux
191distributions.
192.El
193.Ss FORMATS
194Format strings are similar to
195.Xr printf 3
196formats in that they start with
197.Cm % ,
198are then followed by a sequence of formatting characters, and end in
199a character that selects the field of the struct stat which is to be
200formatted.
201If the
202.Cm %
203is immediately followed by one of
204.Cm n ,
205.Cm t ,
206.Cm % ,
207or
208.Cm @ ,
209then a newline character, a tab character, a percent character,
210or the current file number is printed, otherwise the string is
211examined for the following:
212.Pp
213Any of the following optional flags:
214.Bl -tag -width Ds
215.It Cm #
216Selects an alternate output form for string, octal and hexadecimal output.
217String output will be encoded in
218.Xr vis 3
219style.
220Non-zero octal output will have a leading zero.
221Non-zero hexadecimal output will have
222.Dq 0x
223prepended to it.
224.It Cm +
225Asserts that a sign indicating whether a number is positive or negative
226should always be printed.
227Non-negative numbers are not usually printed with a sign.
228.It Cm -
229Aligns string output to the left of the field, instead of to the right.
230.It Cm 0
231Sets the fill character for left padding to the 0 character, instead of
232a space.
233.It space
234Reserves a space at the front of non-negative signed output fields.
235A
236.Sq Cm +
237overrides a space if both are used.
238.El
239.Pp
240Then the following fields:
241.Bl -tag -width Ds
242.It Cm size
243An optional decimal digit string specifying the minimum field width.
244.It Cm prec
245An optional precision composed of a decimal point
246.Sq Cm \&.
247and a decimal digit string that indicates the maximum string length,
248the number of digits to appear after the decimal point in floating point
249output, or the minimum number of digits to appear in numeric output.
250.It Cm fmt
251An optional output format specifier which is one of
252.Cm D ,
253.Cm O ,
254.Cm U ,
255.Cm X ,
256.Cm F ,
257or
258.Cm S .
259These represent signed decimal output, octal output, unsigned decimal
260output, hexadecimal output, floating point output, and string output,
261respectively.
262Some output formats do not apply to all fields.
263Floating point output only applies to timespec fields (the
264.Cm a ,
265.Cm m ,
266and
267.Cm c
268fields).
269.Pp
270The special output specifier
271.Cm S
272may be used to indicate that the output, if
273applicable, should be in string format.
274May be used in combination with
275.Bl -tag -width Ds
276.It Cm amc
277Display date in strftime(3) format.
278.It Cm dr
279Display actual device name.
280.It Cm gu
281Display group or user name.
282.It Cm p
283Display the mode of
284.Ar file
285as in
286.Ic ls -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 `` -\*[Gt] '' into the output.
295Note that the default output format for
296.Cm Y
297is a string, but if specified explicitly, these four characters are
298prepended.
299.El
300.It Cm sub
301An optional sub field specifier (high, middle, or low).
302Only applies to the
303.Cm p ,
304.Cm d ,
305.Cm r ,
306.Cm T ,
307.Cm N ,
308and
309.Cm z
310output formats.
311It can be one of the following:
312.Bl -tag -width Ds
313.It Cm H
314.Dq High
315-- depending on the
316.Cm datum :
317.Bl -tag -compact -width door
318.It Cm d , r
319Major number for devices
320.It Cm p
321.Dq User
322bits from the string form of permissions or the file
323.Dq type
324bits from the numeric forms
325.It Cm T
326The long output form of file type
327.It Cm N
328Directory path of the file, similar to what
329.Xr dirname 1
330would show
331.It Cm z
332File size, rounded to the nearest gigabyte
333.El
334.It Cm M
335.Dq Middle
336-- depending on the
337.Cm datum :
338.Bl -tag -compact -width door
339.It Cm p
340The
341.Dq group
342bits from the string form of permissions or the
343.Dq suid ,
344.Dq sgid ,
345and
346.Dq sticky
347bits from the numeric forms
348.It Cm z
349File size, rounded to the nearest megabyte
350.El
351.It Cm L
352.Dq Low
353-- depending on the
354.Cm datum :
355.Bl -tag -compact -width door
356.It Cm r , d
357Minor number for devices
358.It Cm p
359The
360.Dq other
361bits from the string form of permissions or the
362.Dq user ,
363.Dq group ,
364and
365.Dq other
366bits from the numeric forms
367.It Cm T
368The
369.Ic ls -F
370style output character for file type (the use of
371.Cm L
372here is optional)
373.It Cm N
374Base filename of the file, similar to what
375.Xr basename 1
376would show
377.It Cm z
378File size, rounded to the nearest kilobyte
379.El
380.El
381.It Cm datum
382A required field specifier, being one of the following:
383.Bl -tag -width 11n
384.It Cm d
385Device upon which
386.Ar file
387resides
388.Pq Fa st_dev .
389.It Cm i
390.Ar file Ap s
391inode number
392.Pq Fa st_ino .
393.It Cm p
394File type and permissions
395.Pq Fa st_mode .
396.It Cm l
397Number of hard links to
398.Ar file
399.Pq Fa st_nlink .
400.It Cm u , g
401User-id and group-id of
402.Ar file Ap s
403owner
404.Pq Fa st_uid , st_gid .
405.It Cm r
406Device number for character and block device special files
407.Pq Fa st_rdev .
408.It Cm a , m , c , B
409The time
410.Ar file
411was last accessed or modified, or when the inode was last changed, or
412the birth time of the inode
413.Pq Fa st_atime , st_mtime , st_ctime, st_birthtime .
414.It Cm z
415The size of
416.Ar file
417in bytes
418.Pq Fa st_size .
419.It Cm b
420Number of blocks allocated for
421.Ar file
422.Pq Fa st_blocks .
423.It Cm k
424Optimal file system I/O operation block size
425.Pq Fa st_blksize .
426.It Cm f
427User defined flags for
428.Ar file
429.Pq Fa st_flags .
430.It Cm v
431Inode generation number
432.Pq Fa st_gen .
433.El
434.Pp
435The following five field specifiers are not drawn directly from the
436data in struct stat, but are:
437.Bl -tag -width Ds
438.It Cm N
439The name of the file.
440.It Cm R
441The absolute pathname corresponding to the file.
442.It Cm T
443The file type, either as in
444.Ic ls -F
445or in a more descriptive form if the sub field specifier
446.Cm H
447is given.
448.It Cm Y
449The target of a symbolic link.
450.It Cm Z
451Expands to
452.Dq Ar major , Ns Ar minor
453from the rdev field for character or block
454special devices and gives size output for all others.
455.El
456.El
457.Pp
458Only the
459.Cm %
460and the field specifier are required.
461Most field specifiers default to
462.Cm U
463as an output form, with the
464exception of
465.Cm p
466which defaults to
467.Cm O ;
468.Cm a , m ,
469and
470.Cm c
471which default to
472.Cm D ;
473and
474.Cm Y , T ,
475and
476.Cm N ,
477which default to
478.Cm S .
479.Sh EXIT STATUS
480.Ex -std
481.Sh EXAMPLES
482If no options are specified, the default format is
483"%d %i %Sp %l %Su %Sg %r %z \e"%Sa\e" \e"%Sm\e" \e"%Sc\e" \e"%SB\e" %k %b %#Xf %N".
484.Bd -literal -offset indent
485\*[Gt] stat /tmp/bar
4860 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
487.Ed
488.Pp
489This example produces output very similar to that from
490.Ic find ... -ls
491(except that
492.Xr find 1
493displays the time in a different format, and
494.Xr find 1
495sometimes adds one or more spaces after the comma in
496.Dq Ar major , Ns Ar minor
497for device nodes):
498.Bd -literal -offset indent
499\*[Gt] stat -f "%7i %6b %-11Sp %3l %-17Su %-17Sg %9Z %Sm %N%SY" /tmp/bar
500  78852      0 -rw-r--r--    1 root              wheel                     0 Jul  8 10:26:03 2004 /tmp/bar
501
502\*[Gt] find /tmp/bar -ls -exit
503  78852      0 -rw-r--r--    1 root              wheel                     0 Jul  8  2004 /tmp/bar
504.Ed
505.Pp
506This example produces output very similar to that from
507.Ic ls -lTd
508(except that
509.Xr ls 1
510adjusts the column spacing differently when listing multiple files,
511and
512.Xr ls 1
513adds at least one space after the comma in
514.Dq Ar major , Ns Ar minor
515for device nodes):
516.Bd -literal -offset indent
517\*[Gt] stat -f "%-11Sp %l %Su  %Sg  %Z %Sm %N%SY" /tmp/bar
518-rw-r--r--  1 root  wheel  0 Jul  8 10:26:03 2004 /tmp/bar
519
520\*[Gt] ls -lTd /tmp/bar
521-rw-r--r--  1 root  wheel  0 Jul  8 10:26:03 2004 /tmp/bar
522.Ed
523.Pp
524Given a symbolic link
525.Dq foo
526that points from
527.Pa /tmp/foo
528to
529.Pa / ,
530you would use
531.Nm
532as follows:
533.Bd -literal -offset indent
534\*[Gt] stat -F /tmp/foo
535lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] /
536
537\*[Gt] stat -LF /tmp/foo
538drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
539.Ed
540.Pp
541To initialize some shell-variables, you could use the
542.Fl s
543flag as follows:
544.Bd -literal -offset indent
545\*[Gt] csh
546% eval set `stat -s .cshrc`
547% echo $st_size $st_mtime
5481148 1015432481
549
550\*[Gt] sh
551$ eval $(stat -s .profile)
552$ echo $st_size $st_mtime
5531148 1015432481
554.Ed
555.Pp
556In order to get a list of the kind of files including files pointed to if the
557file is a symbolic link, you could use the following format:
558.Bd -literal -offset indent
559$ stat -f "%N: %HT%SY" /tmp/*
560/tmp/bar: Symbolic Link -\*[Gt] /tmp/foo
561/tmp/output25568: Regular File
562/tmp/blah: Directory
563/tmp/foo: Symbolic Link -\*[Gt] /
564.Ed
565.Pp
566In order to get a list of the devices, their types and the major and minor
567device numbers, formatted with tabs and linebreaks, you could use the
568following format:
569.Bd -literal -offset indent
570stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
571[...]
572Name: /dev/wt8
573        Type: Block Device
574        Major: 3
575        Minor: 8
576
577Name: /dev/zero
578        Type: Character Device
579        Major: 2
580        Minor: 12
581.Ed
582.Pp
583In order to determine the permissions set on a file separately, you could use
584the following format:
585.Bd -literal -offset indent
586\*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" .
587drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x
588.Ed
589.Pp
590In order to determine the three files that have been modified most recently,
591you could use the following format:
592.Bd -literal -offset indent
593\*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
594Apr 25 11:47:00 2002 /tmp/blah
595Apr 25 10:36:34 2002 /tmp/bar
596Apr 24 16:47:35 2002 /tmp/foo
597.Ed
598.Pp
599User names, group names, and file names that contain spaces
600or other special characters may be encoded in
601.Xr vis 3
602style, using the
603.Cm \&#
604modifier:
605.Bd -literal -offset indent
606\*[Gt] ln -s 'target with spaces' 'link with spaces'
607\*[Gt] stat -f "%#N%#SY" 'link with spaces'
608link\eswith\esspaces -\*[Gt] target\eswith\esspaces
609.Ed
610.Sh SEE ALSO
611.Xr basename 1 ,
612.Xr dirname 1 ,
613.Xr file 1 ,
614.Xr ls 1 ,
615.Xr lstat 2 ,
616.Xr readlink 2 ,
617.Xr stat 2 ,
618.Xr printf 3 ,
619.Xr strftime 3
620.Sh HISTORY
621The
622.Nm
623utility appeared in
624.Nx 1.6 .
625.Sh AUTHORS
626.An -nosplit
627The
628.Nm
629utility was written by
630.An Andrew Brown
631.Aq atatat@NetBSD.org .
632This man page was written by
633.An Jan Schaumann
634.Aq jschauma@NetBSD.org .
635