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