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