| blob | 58ae3a5c94490fd699e84b5b11fbcb6f6beaac16 |
1 .\" $NetBSD: stat.1,v 1.25 2008/11/07 15:33:31 reed 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
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_blksize ,
98 .Fa st_blocks ,
99 and
100 .Fa st_flags
101 fields, in that order.
102 .Pp
103 The options are as follows:
104 .Bl -tag -width XFXformatXXX
105 .It Fl F
106 As in
107 .Xr ls 1 ,
108 display a slash
109 .Pq Sq /
110 immediately after each pathname that is a directory, an
111 asterisk
112 .Pq Sq *
113 after each that is executable, an at sign
114 .Pq Sq @
115 after each symbolic link, a percent sign
116 .Pq Sq %
117 after each whiteout, an equal sign
118 .Pq Sq =
119 after each socket, and a vertical bar
120 .Pq Sq \&|
121 after each that is a FIFO.
122 The use of
123 .Fl F
124 implies
125 .Fl l .
126 .It Fl f Ar format
127 Display information using the specified format.
128 See the
129 .Sx FORMATS
130 section for a description of valid formats.
131 .It Fl L
132 Use
133 .Xr stat 2
134 instead of
135 .Xr lstat 2 .
136 The information reported by
137 .Nm
138 will refer to the target of
139 .Ar file ,
140 if file is a symbolic link, and not to
141 .Ar file
142 itself.
143 .It Fl l
144 Display output in
145 .Ic ls Fl lT
146 format.
147 .It Fl n
148 Do not force a newline to appear at the end of each piece of output.
149 .It Fl q
150 Suppress failure messages if calls to
151 .Xr stat 2
152 or
153 .Xr lstat 2
154 fail.
155 When run as
156 .Nm readlink ,
157 error messages are automatically suppressed.
158 .It Fl r
159 Display raw information.
160 That is, for all the fields in the stat-structure,
161 display the raw, numerical value (for example, times in seconds since the
162 epoch, etc.)
163 .It Fl s
164 Display information in
165 .Dq shell output ,
166 suitable for initializing variables.
167 .It Fl t Ar timefmt
168 Display timestamps using the specified format.
169 This format is
170 passed directly to
171 .Xr strftime 3 .
172 .It Fl x
173 Display information in a more verbose way as known from some Linux
174 distributions.
175 .El
176 .Ss FORMATS
177 Format strings are similar to
178 .Xr printf 3
179 formats in that they start with
180 .Cm % ,
181 are then followed by a sequence of formatting characters, and end in
182 a character that selects the field of the struct stat which is to be
183 formatted.
184 If the
185 .Cm %
186 is immediately followed by one of
187 .Cm n ,
188 .Cm t ,
189 .Cm % ,
190 or
191 .Cm @ ,
192 then a newline character, a tab character, a percent character,
193 or the current file number is printed, otherwise the string is
194 examined for the following:
195 .Pp
196 Any of the following optional flags:
197 .Bl -tag -width Ds
198 .It Cm #
199 Selects an alternate output form for octal and hexadecimal output.
200 Non-zero octal output will have a leading zero, and non-zero
201 hexadecimal output will have
202 .Dq 0x
203 prepended to it.
204 .It Cm +
205 Asserts that a sign indicating whether a number is positive or negative
206 should always be printed.
207 Non-negative numbers are not usually printed with a sign.
208 .It Cm -
209 Aligns string output to the left of the field, instead of to the right.
210 .It Cm 0
211 Sets the fill character for left padding to the 0 character, instead of
212 a space.
213 .It space
214 Reserves a space at the front of non-negative signed output fields.
215 A
216 .Sq Cm +
217 overrides a space if both are used.
218 .El
219 .Pp
220 Then the following fields:
221 .Bl -tag -width Ds
222 .It Cm size
223 An optional decimal digit string specifying the minimum field width.
224 .It Cm prec
225 An optional precision composed of a decimal point
226 .Sq Cm \&.
227 and a decimal digit string that indicates the maximum string length,
228 the number of digits to appear after the decimal point in floating point
229 output, or the minimum number of digits to appear in numeric output.
230 .It Cm fmt
231 An optional output format specifier which is one of
232 .Cm D ,
233 .Cm O ,
234 .Cm U ,
235 .Cm X ,
236 .Cm F ,
237 or
238 .Cm S .
239 These represent signed decimal output, octal output, unsigned decimal
240 output, hexadecimal output, floating point output, and string output,
241 respectively.
242 Some output formats do not apply to all fields.
243 Floating point output only applies to timespec fields (the
244 .Cm a ,
245 .Cm m ,
246 and
247 .Cm c
248 fields).
249 .Pp
250 The special output specifier
251 .Cm S
252 may be used to indicate that the output, if
253 applicable, should be in string format.
254 May be used in combination with
255 .Bl -tag -width Ds
256 .It Cm amc
257 Display date in strftime(3) format.
258 .It Cm dr
259 Display actual device name.
260 .It Cm gu
261 Display group or user name.
262 .It Cm p
263 Display the mode of
264 .Ar file
265 as in
266 .Ic ls -lTd .
267 .It Cm N
268 Displays the name of
269 .Ar file .
270 .It Cm T
271 Displays the type of
272 .Ar file .
273 .It Cm Y
274 Insert a `` -\*[Gt] '' into the output.
275 Note that the default output format for
276 .Cm Y
277 is a string, but if specified explicitly, these four characters are
278 prepended.
279 .El
280 .It Cm sub
281 An optional sub field specifier (high, middle, or low).
282 Only applies to the
283 .Cm p ,
284 .Cm d ,
285 .Cm r ,
286 .Cm T ,
287 .Cm N ,
288 and
289 .Cm z
290 output formats.
291 It 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
299 Major number for devices
300 .It Cm p
301 .Dq User
302 bits from the string form of permissions or the file
303 .Dq type
304 bits from the numeric forms
305 .It Cm T
306 The long output form of file type
307 .It Cm N
308 Directory path of the file, similar to what
309 .Xr dirname 1
310 would show
311 .It Cm z
312 File 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
320 The
321 .Dq group
322 bits from the string form of permissions or the
323 .Dq suid ,
324 .Dq sgid ,
325 and
326 .Dq sticky
327 bits from the numeric forms
328 .It Cm z
329 File 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
337 Minor number for devices
338 .It Cm p
339 The
340 .Dq other
341 bits from the string form of permissions or the
342 .Dq user ,
343 .Dq group ,
344 and
345 .Dq other
346 bits from the numeric forms
347 .It Cm T
348 The
349 .Ic ls -F
350 style output character for file type (the use of
351 .Cm L
352 here is optional)
353 .It Cm N
354 Base filename of the file, similar to what
355 .Xr basename 1
356 would show
357 .It Cm z
358 File size, rounded to the nearest kilobyte
359 .El
360 .El
361 .It Cm datum
362 A required field specifier, being one of the following:
363 .Bl -tag -width 11n
364 .It Cm d
365 Device upon which
366 .Ar file
367 resides
368 .Pq Fa st_dev .
369 .It Cm i
370 .Ar file Ap s
371 inode number
372 .Pq Fa st_ino .
373 .It Cm p
374 File type and permissions
375 .Pq Fa st_mode .
376 .It Cm l
377 Number of hard links to
378 .Ar file
379 .Pq Fa st_nlink .
380 .It Cm u , g
381 User-id and group-id of
382 .Ar file Ap s
383 owner
384 .Pq Fa st_uid , st_gid .
385 .It Cm r
386 Device number for character and block device special files
387 .Pq Fa st_rdev .
388 .It Cm a , m , c , B
389 The time
390 .Ar file
391 was last accessed or modified, or when the inode was last changed, or
392 the birth time of the inode
393 .Pq Fa st_atime , st_mtime , st_ctime, st_birthtime .
394 .It Cm z
395 The size of
396 .Ar file
397 in bytes
398 .Pq Fa st_size .
399 .It Cm b
400 Number of blocks allocated for
401 .Ar file
402 .Pq Fa st_blocks .
403 .It Cm k
404 Optimal file system I/O operation block size
405 .Pq Fa st_blksize .
406 .It Cm f
407 User defined flags for
408 .Ar file
409 .Pq Fa st_flags .
410 .It Cm v
411 Inode generation number
412 .Pq Fa st_gen .
413 .El
414 .Pp
415 The following five field specifiers are not drawn directly from the
416 data in struct stat, but are:
417 .Bl -tag -width Ds
418 .It Cm N
419 The name of the file.
420 .It Cm R
421 The absolute pathname corresponding to the file.
422 .It Cm T
423 The file type, either as in
424 .Ic ls -F
425 or in a more descriptive form if the sub field specifier
426 .Cm H
427 is given.
428 .It Cm Y
429 The target of a symbolic link.
430 .It Cm Z
431 Expands to
432 .Dq major,minor
433 from the rdev field for character or block
434 special devices and gives size output for all others.
435 .El
436 .El
437 .Pp
438 Only the
439 .Cm %
440 and the field specifier are required.
441 Most field specifiers default to
442 .Cm U
443 as an output form, with the
444 exception of
445 .Cm p
446 which defaults to
447 .Cm O ;
448 .Cm a , m ,
449 and
450 .Cm c
451 which default to
452 .Cm D ;
453 and
454 .Cm Y , T ,
455 and
456 .Cm N ,
457 which default to
458 .Cm S .
459 .Sh EXIT STATUS
460 .Nm
461 exits 0 on success, and \*[Gt]0 if an error occurred.
462 .Sh EXAMPLES
463 If 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
467 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
468 .Ed
469 .Pp
470 Given a symbolic link
471 .Dq foo
472 that points from
473 .Pa /tmp/foo
474 to
475 .Pa / ,
476 you would use
477 .Nm
478 as follows:
479 .Bd -literal -offset indent
480 \*[Gt] stat -F /tmp/foo
481 lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] /
483 \*[Gt] stat -LF /tmp/foo
484 drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
485 .Ed
486 .Pp
487 To initialize some shell-variables, you could use the
488 .Fl s
489 flag as follows:
490 .Bd -literal -offset indent
491 \*[Gt] csh
492 % eval set `stat -s .cshrc`
493 % echo $st_size $st_mtime
494 1148 1015432481
496 \*[Gt] sh
497 $ eval $(stat -s .profile)
498 $ echo $st_size $st_mtime
499 1148 1015432481
500 .Ed
501 .Pp
502 In order to get a list of the kind of files including files pointed to if the
503 file 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
512 In order to get a list of the devices, their types and the major and minor
513 device numbers, formatted with tabs and linebreaks, you could use the
514 following format:
515 .Bd -literal -offset indent
516 stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
517 [...]
518 Name: /dev/wt8
519 Type: Block Device
520 Major: 3
521 Minor: 8
523 Name: /dev/zero
524 Type: Character Device
525 Major: 2
526 Minor: 12
527 .Ed
528 .Pp
529 In order to determine the permissions set on a file separately, you could use
530 the following format:
531 .Bd -literal -offset indent
532 \*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" .
533 drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x
534 .Ed
535 .Pp
536 In order to determine the three files that have been modified most recently,
537 you 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-
540 Apr 25 11:47:00 2002 /tmp/blah
541 Apr 25 10:36:34 2002 /tmp/bar
542 Apr 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
555 The
556 .Nm
557 utility appeared in
558 .Nx 1.6 .
559 .Sh AUTHORS
560 .An -nosplit
561 The
562 .Nm
563 utility was written by
564 .An Andrew Brown
565 .Aq atatat@NetBSD.org .
566 This man page was written by
567 .An Jan Schaumann
568 .Aq jschauma@NetBSD.org .