| blob | 98c279576aee165e2ab48e36c63309081db08b96 |
1 .\" $NetBSD: stat.1,v 1.28 2010/04/05 21:25:01 joerg 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_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 .It Fl t Ar timefmt
169 Display timestamps using the specified format.
170 This format is
171 passed directly to
172 .Xr strftime 3 .
173 .It Fl x
174 Display information in a more verbose way as known from some Linux
175 distributions.
176 .El
177 .Ss FORMATS
178 Format strings are similar to
179 .Xr printf 3
180 formats in that they start with
181 .Cm % ,
182 are then followed by a sequence of formatting characters, and end in
183 a character that selects the field of the struct stat which is to be
184 formatted.
185 If the
186 .Cm %
187 is immediately followed by one of
188 .Cm n ,
189 .Cm t ,
190 .Cm % ,
191 or
192 .Cm @ ,
193 then a newline character, a tab character, a percent character,
194 or the current file number is printed, otherwise the string is
195 examined for the following:
196 .Pp
197 Any of the following optional flags:
198 .Bl -tag -width Ds
199 .It Cm #
200 Selects an alternate output form for octal and hexadecimal output.
201 Non-zero octal output will have a leading zero, and non-zero
202 hexadecimal output will have
203 .Dq 0x
204 prepended to it.
205 .It Cm +
206 Asserts that a sign indicating whether a number is positive or negative
207 should always be printed.
208 Non-negative numbers are not usually printed with a sign.
209 .It Cm -
210 Aligns string output to the left of the field, instead of to the right.
211 .It Cm 0
212 Sets the fill character for left padding to the 0 character, instead of
213 a space.
214 .It space
215 Reserves a space at the front of non-negative signed output fields.
216 A
217 .Sq Cm +
218 overrides a space if both are used.
219 .El
220 .Pp
221 Then the following fields:
222 .Bl -tag -width Ds
223 .It Cm size
224 An optional decimal digit string specifying the minimum field width.
225 .It Cm prec
226 An optional precision composed of a decimal point
227 .Sq Cm \&.
228 and a decimal digit string that indicates the maximum string length,
229 the number of digits to appear after the decimal point in floating point
230 output, or the minimum number of digits to appear in numeric output.
231 .It Cm fmt
232 An optional output format specifier which is one of
233 .Cm D ,
234 .Cm O ,
235 .Cm U ,
236 .Cm X ,
237 .Cm F ,
238 or
239 .Cm S .
240 These represent signed decimal output, octal output, unsigned decimal
241 output, hexadecimal output, floating point output, and string output,
242 respectively.
243 Some output formats do not apply to all fields.
244 Floating point output only applies to timespec fields (the
245 .Cm a ,
246 .Cm m ,
247 and
248 .Cm c
249 fields).
250 .Pp
251 The special output specifier
252 .Cm S
253 may be used to indicate that the output, if
254 applicable, should be in string format.
255 May be used in combination with
256 .Bl -tag -width Ds
257 .It Cm amc
258 Display date in strftime(3) format.
259 .It Cm dr
260 Display actual device name.
261 .It Cm gu
262 Display group or user name.
263 .It Cm p
264 Display the mode of
265 .Ar file
266 as in
267 .Ic ls -lTd .
268 .It Cm N
269 Displays the name of
270 .Ar file .
271 .It Cm T
272 Displays the type of
273 .Ar file .
274 .It Cm Y
275 Insert a `` -\*[Gt] '' into the output.
276 Note that the default output format for
277 .Cm Y
278 is a string, but if specified explicitly, these four characters are
279 prepended.
280 .El
281 .It Cm sub
282 An optional sub field specifier (high, middle, or low).
283 Only applies to the
284 .Cm p ,
285 .Cm d ,
286 .Cm r ,
287 .Cm T ,
288 .Cm N ,
289 and
290 .Cm z
291 output formats.
292 It can be one of the following:
293 .Bl -tag -width Ds
294 .It Cm H
295 .Dq High
296 -- depending on the
297 .Cm datum :
298 .Bl -tag -compact -width door
299 .It Cm d , r
300 Major number for devices
301 .It Cm p
302 .Dq User
303 bits from the string form of permissions or the file
304 .Dq type
305 bits from the numeric forms
306 .It Cm T
307 The long output form of file type
308 .It Cm N
309 Directory path of the file, similar to what
310 .Xr dirname 1
311 would show
312 .It Cm z
313 File size, rounded to the nearest gigabyte
314 .El
315 .It Cm M
316 .Dq Middle
317 -- depending on the
318 .Cm datum :
319 .Bl -tag -compact -width door
320 .It Cm p
321 The
322 .Dq group
323 bits from the string form of permissions or the
324 .Dq suid ,
325 .Dq sgid ,
326 and
327 .Dq sticky
328 bits from the numeric forms
329 .It Cm z
330 File size, rounded to the nearest megabyte
331 .El
332 .It Cm L
333 .Dq Low
334 -- depending on the
335 .Cm datum :
336 .Bl -tag -compact -width door
337 .It Cm r , d
338 Minor number for devices
339 .It Cm p
340 The
341 .Dq other
342 bits from the string form of permissions or the
343 .Dq user ,
344 .Dq group ,
345 and
346 .Dq other
347 bits from the numeric forms
348 .It Cm T
349 The
350 .Ic ls -F
351 style output character for file type (the use of
352 .Cm L
353 here is optional)
354 .It Cm N
355 Base filename of the file, similar to what
356 .Xr basename 1
357 would show
358 .It Cm z
359 File size, rounded to the nearest kilobyte
360 .El
361 .El
362 .It Cm datum
363 A required field specifier, being one of the following:
364 .Bl -tag -width 11n
365 .It Cm d
366 Device upon which
367 .Ar file
368 resides
369 .Pq Fa st_dev .
370 .It Cm i
371 .Ar file Ap s
372 inode number
373 .Pq Fa st_ino .
374 .It Cm p
375 File type and permissions
376 .Pq Fa st_mode .
377 .It Cm l
378 Number of hard links to
379 .Ar file
380 .Pq Fa st_nlink .
381 .It Cm u , g
382 User-id and group-id of
383 .Ar file Ap s
384 owner
385 .Pq Fa st_uid , st_gid .
386 .It Cm r
387 Device number for character and block device special files
388 .Pq Fa st_rdev .
389 .It Cm a , m , c , B
390 The time
391 .Ar file
392 was last accessed or modified, or when the inode was last changed, or
393 the birth time of the inode
394 .Pq Fa st_atime , st_mtime , st_ctime, st_birthtime .
395 .It Cm z
396 The size of
397 .Ar file
398 in bytes
399 .Pq Fa st_size .
400 .It Cm b
401 Number of blocks allocated for
402 .Ar file
403 .Pq Fa st_blocks .
404 .It Cm k
405 Optimal file system I/O operation block size
406 .Pq Fa st_blksize .
407 .It Cm f
408 User defined flags for
409 .Ar file
410 .Pq Fa st_flags .
411 .It Cm v
412 Inode generation number
413 .Pq Fa st_gen .
414 .El
415 .Pp
416 The following five field specifiers are not drawn directly from the
417 data in struct stat, but are:
418 .Bl -tag -width Ds
419 .It Cm N
420 The name of the file.
421 .It Cm R
422 The absolute pathname corresponding to the file.
423 .It Cm T
424 The file type, either as in
425 .Ic ls -F
426 or in a more descriptive form if the sub field specifier
427 .Cm H
428 is given.
429 .It Cm Y
430 The target of a symbolic link.
431 .It Cm Z
432 Expands to
433 .Dq major,minor
434 from the rdev field for character or block
435 special devices and gives size output for all others.
436 .El
437 .El
438 .Pp
439 Only the
440 .Cm %
441 and the field specifier are required.
442 Most field specifiers default to
443 .Cm U
444 as an output form, with the
445 exception of
446 .Cm p
447 which defaults to
448 .Cm O ;
449 .Cm a , m ,
450 and
451 .Cm c
452 which default to
453 .Cm D ;
454 and
455 .Cm Y , T ,
456 and
457 .Cm N ,
458 which default to
459 .Cm S .
460 .Sh EXIT STATUS
461 .Nm
462 exits 0 on success, and \*[Gt]0 if an error occurred.
463 .Sh EXAMPLES
464 If no options are specified, the default format is
465 "%d %i %Sp %l %Su %Sg %r %z \e"%Sa\e" \e"%Sm\e" \e"%Sc\e" \e"%SB\e" %k %b %#Xf %N".
466 .Bd -literal -offset indent
467 \*[Gt] stat /tmp/bar
468 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
469 .Ed
470 .Pp
471 Given a symbolic link
472 .Dq foo
473 that points from
474 .Pa /tmp/foo
475 to
476 .Pa / ,
477 you would use
478 .Nm
479 as follows:
480 .Bd -literal -offset indent
481 \*[Gt] stat -F /tmp/foo
482 lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] /
484 \*[Gt] stat -LF /tmp/foo
485 drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
486 .Ed
487 .Pp
488 To initialize some shell-variables, you could use the
489 .Fl s
490 flag as follows:
491 .Bd -literal -offset indent
492 \*[Gt] csh
493 % eval set `stat -s .cshrc`
494 % echo $st_size $st_mtime
495 1148 1015432481
497 \*[Gt] sh
498 $ eval $(stat -s .profile)
499 $ echo $st_size $st_mtime
500 1148 1015432481
501 .Ed
502 .Pp
503 In order to get a list of the kind of files including files pointed to if the
504 file is a symbolic link, you could use the following format:
505 .Bd -literal -offset indent
506 $ stat -f "%N: %HT%SY" /tmp/*
507 /tmp/bar: Symbolic Link -\*[Gt] /tmp/foo
508 /tmp/output25568: Regular File
509 /tmp/blah: Directory
510 /tmp/foo: Symbolic Link -\*[Gt] /
511 .Ed
512 .Pp
513 In order to get a list of the devices, their types and the major and minor
514 device numbers, formatted with tabs and linebreaks, you could use the
515 following format:
516 .Bd -literal -offset indent
517 stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
518 [...]
519 Name: /dev/wt8
520 Type: Block Device
521 Major: 3
522 Minor: 8
524 Name: /dev/zero
525 Type: Character Device
526 Major: 2
527 Minor: 12
528 .Ed
529 .Pp
530 In order to determine the permissions set on a file separately, you could use
531 the following format:
532 .Bd -literal -offset indent
533 \*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" .
534 drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x
535 .Ed
536 .Pp
537 In order to determine the three files that have been modified most recently,
538 you could use the following format:
539 .Bd -literal -offset indent
540 \*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
541 Apr 25 11:47:00 2002 /tmp/blah
542 Apr 25 10:36:34 2002 /tmp/bar
543 Apr 24 16:47:35 2002 /tmp/foo
544 .Ed
545 .Sh SEE ALSO
546 .Xr basename 1 ,
547 .Xr dirname 1 ,
548 .Xr file 1 ,
549 .Xr ls 1 ,
550 .Xr lstat 2 ,
551 .Xr readlink 2 ,
552 .Xr stat 2 ,
553 .Xr printf 3 ,
554 .Xr strftime 3
555 .Sh HISTORY
556 The
557 .Nm
558 utility appeared in
559 .Nx 1.6 .
560 .Sh AUTHORS
561 .An -nosplit
562 The
563 .Nm
564 utility was written by
565 .An Andrew Brown
566 .Aq atatat@NetBSD.org .
567 This man page was written by
568 .An Jan Schaumann
569 .Aq jschauma@NetBSD.org .