Merge branch 'vendor/OPENSSL'
[dragonfly.git] / usr.bin / stat / stat.1
1 .\"     $NetBSD: stat.1,v 1.11 2003/05/08 13:07:10 wiz Exp $
2 .\"     $DragonFly: src/usr.bin/stat/stat.1,v 1.6 2007/11/04 16:33:19 swildner Exp $
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 .\" 3. All advertising materials mentioning features or use of this software
18 .\"    must display the following acknowledgement:
19 .\"        This product includes software developed by the NetBSD
20 .\"        Foundation, Inc. and its contributors.
21 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
22 .\"    contributors may be used to endorse or promote products derived
23 .\"    from this software without specific prior written permission.
24 .\"
25 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35 .\" POSSIBILITY OF SUCH DAMAGE.
36 .\"
37 .\" $FreeBSD: src/usr.bin/stat/stat.1,v 1.8 2005/06/14 11:50:53 ru Exp $
38 .\"
39 .Dd May 8, 2003
40 .Dt STAT 1
41 .Os
42 .Sh NAME
43 .Nm stat ,
44 .Nm readlink
45 .Nd display file status
46 .Sh SYNOPSIS
47 .Nm
48 .Op Fl FLnq
49 .Op Fl f Ar format | Fl l | r | s | x
50 .Op Fl t Ar timefmt
51 .Op Ar
52 .Nm readlink
53 .Op Fl n
54 .Op Ar
55 .Sh DESCRIPTION
56 The
57 .Nm
58 utility displays information about the file pointed to by
59 .Ar file .
60 Read, write or execute permissions of the named file are not required, but
61 all directories listed in the path name leading to the file must be
62 searchable.
63 If no argument is given,
64 .Nm
65 displays information about the file descriptor for standard input.
66 .Pp
67 When invoked as
68 .Nm readlink ,
69 only the target of the symbolic link is printed.
70 If the given argument is not a symbolic link,
71 .Nm readlink
72 will print nothing and exit with an error.
73 .Pp
74 The information displayed is obtained by calling
75 .Xr lstat 2
76 with the given argument and evaluating the returned structure.
77 .Pp
78 The options are as follows:
79 .Bl -tag -width indent
80 .It Fl F
81 As in
82 .Xr ls 1 ,
83 display a slash
84 .Pq Ql /
85 immediately after each pathname that is a directory,
86 an asterisk
87 .Pq Ql *
88 after each that is executable,
89 an at sign
90 .Pq Ql @
91 after each symbolic link,
92 a percent sign
93 .Pq Ql %
94 after each whiteout,
95 an equal sign
96 .Pq Ql =
97 after each socket,
98 and a vertical bar
99 .Pq Ql |
100 after each that is a FIFO.
101 The use of
102 .Fl F
103 implies
104 .Fl l .
105 .It Fl L
106 Use
107 .Xr stat 2
108 instead of
109 .Xr lstat 2 .
110 The information reported by
111 .Nm
112 will refer to the target of
113 .Ar file ,
114 if file is a symbolic link, and not to
115 .Ar file
116 itself.
117 .It Fl n
118 Do not force a newline to appear at the end of each piece of output.
119 .It Fl q
120 Suppress failure messages if calls to
121 .Xr stat 2
122 or
123 .Xr lstat 2
124 fail.
125 When run as
126 .Nm readlink ,
127 error messages are automatically suppressed.
128 .It Fl f Ar format
129 Display information using the specified format.
130 See the
131 .Sx Formats
132 section for a description of valid formats.
133 .It Fl l
134 Display output in
135 .Nm ls Fl lT
136 format.
137 .It Fl r
138 Display raw information.
139 That is, for all the fields in the
140 .Vt stat
141 structure,
142 display the raw, numerical value (for example, times in seconds since the
143 epoch, etc.).
144 .It Fl s
145 Display information in
146 .Dq "shell output" ,
147 suitable for initializing variables.
148 .It Fl x
149 Display information in a more verbose way as known from some
150 .Tn Linux
151 distributions.
152 .It Fl t Ar timefmt
153 Display timestamps using the specified format.
154 This format is
155 passed directly to
156 .Xr strftime 3 .
157 .El
158 .Ss Formats
159 Format strings are similar to
160 .Xr printf 3
161 formats in that they start with
162 .Cm % ,
163 are then followed by a sequence of formatting characters, and end in
164 a character that selects the field of the
165 .Vt "struct stat"
166 which is to be formatted.
167 If the
168 .Cm %
169 is immediately followed by one of
170 .Cm n , t , % ,
171 or
172 .Cm @ ,
173 then a newline character, a tab character, a percent character,
174 or the current file number is printed, otherwise the string is
175 examined for the following:
176 .Pp
177 Any of the following optional flags:
178 .Bl -tag -width indent
179 .It Cm #
180 Selects an alternate output form for octal and hexadecimal output.
181 Non-zero octal output will have a leading zero, and non-zero
182 hexadecimal output will have
183 .Dq Li 0x
184 prepended to it.
185 .It Cm +
186 Asserts that a sign indicating whether a number is positive or negative
187 should always be printed.
188 Non-negative numbers are not usually printed
189 with a sign.
190 .It Cm -
191 Aligns string output to the left of the field, instead of to the right.
192 .It Cm 0
193 Sets the fill character for left padding to the
194 .Ql 0
195 character, instead of a space.
196 .It space
197 Reserves a space at the front of non-negative signed output fields.
198 A
199 .Sq Cm +
200 overrides a space if both are used.
201 .El
202 .Pp
203 Then the following fields:
204 .Bl -tag -width indent
205 .It Ar size
206 An optional decimal digit string specifying the minimum field width.
207 .It Ar prec
208 An optional precision composed of a decimal point
209 .Sq Cm \&.
210 and a decimal digit string that indicates the maximum string length,
211 the number of digits to appear after the decimal point in floating point
212 output, or the minimum number of digits to appear in numeric output.
213 .It Ar fmt
214 An optional output format specifier which is one of
215 .Cm D , O , U , X , F ,
216 or
217 .Cm S .
218 These represent signed decimal output, octal output, unsigned decimal
219 output, hexadecimal output, floating point output, and string output,
220 respectively.
221 Some output formats do not apply to all fields.
222 Floating point output only applies to
223 .Vt timespec
224 fields (the
225 .Cm a , m ,
226 and
227 .Cm c
228 fields).
229 .Pp
230 The special output specifier
231 .Cm S
232 may be used to indicate that the output, if
233 applicable, should be in string format.
234 May be used in combination with:
235 .Bl -tag -width indent
236 .It Cm amc
237 Display date in
238 .Xr strftime 3
239 format.
240 .It Cm dr
241 Display actual device name.
242 .It Cm gu
243 Display group or user name.
244 .It Cm p
245 Display the mode of
246 .Ar file
247 as in
248 .Nm ls Fl lTd .
249 .It Cm N
250 Displays the name of
251 .Ar file .
252 .It Cm T
253 Displays the type of
254 .Ar file .
255 .It Cm Y
256 Insert a
257 .Dq Li " -\*[Gt] "
258 into the output.
259 Note that the default output format
260 for
261 .Cm Y
262 is a string, but if specified explicitly, these four characters are
263 prepended.
264 .El
265 .It Ar sub
266 An optional sub field specifier (high, middle, low).
267 Only applies to
268 the
269 .Cm p , d , r ,
270 and
271 .Cm T
272 output formats.
273 It can be one of the following:
274 .Bl -tag -width indent
275 .It Cm H
276 .Dq High
277 \(em
278 specifies the major number for devices from
279 .Cm r
280 or
281 .Cm d ,
282 the
283 .Dq user
284 bits for permissions from the string form of
285 .Cm p ,
286 the file
287 .Dq type
288 bits from the numeric forms of
289 .Cm p ,
290 and the long output form of
291 .Cm T .
292 .It Cm L
293 .Dq Low
294 \(em
295 specifies the minor number for devices from
296 .Cm r
297 or
298 .Cm d ,
299 the
300 .Dq other
301 bits for permissions from the string form of
302 .Cm p ,
303 the
304 .Dq user ,
305 .Dq group ,
306 and
307 .Dq other
308 bits from the numeric forms of
309 .Cm p ,
310 and the
311 .Nm ls Fl F
312 style output character for file type when used with
313 .Cm T
314 (the use of
315 .Cm L
316 for this is optional).
317 .It Cm M
318 .Dq Middle
319 \(em
320 specifies the
321 .Dq group
322 bits for permissions from the
323 string output form of
324 .Cm p ,
325 or the
326 .Dq suid ,
327 .Dq sgid ,
328 and
329 .Dq sticky
330 bits for the numeric forms of
331 .Cm p .
332 .El
333 .It Ar datum
334 A required field specifier, being one of the following:
335 .Bl -tag -width indent
336 .It Cm d
337 Device upon which
338 .Ar file
339 resides.
340 .It Cm i
341 .Ar file Ns 's
342 inode number.
343 .It Cm p
344 File type and permissions.
345 .It Cm l
346 Number of hard links to
347 .Ar file .
348 .It Cm u , g
349 User ID and group ID of
350 .Ar file Ns 's
351 owner.
352 .It Cm r
353 Device number for character and block device special files.
354 .It Cm a , m , c , B
355 The time
356 .Ar file
357 was last accessed or modified, or when the inode was last changed, or
358 the birth time of the inode.
359 .It Cm z
360 The size of
361 .Ar file
362 in bytes.
363 .It Cm b
364 Number of blocks allocated for
365 .Ar file .
366 .It Cm k
367 Optimal file system I/O operation block size.
368 .It Cm f
369 User defined flags for
370 .Ar file .
371 .It Cm v
372 Inode generation number.
373 .El
374 .Pp
375 The following four field specifiers are not drawn directly from the
376 data in
377 .Vt "struct stat" ,
378 but are:
379 .Bl -tag -width indent
380 .It Cm N
381 The name of the file.
382 .It Cm T
383 The file type, either as in
384 .Nm ls Fl F
385 or in a more descriptive form if the
386 .Ar sub
387 field specifier
388 .Cm H
389 is given.
390 .It Cm Y
391 The target of a symbolic link.
392 .It Cm Z
393 Expands to
394 .Dq major,minor
395 from the
396 .Va rdev
397 field for character or block
398 special devices and gives size output for all others.
399 .El
400 .El
401 .Pp
402 Only the
403 .Cm %
404 and the field specifier are required.
405 Most field specifiers default to
406 .Cm U
407 as an output form, with the
408 exception of
409 .Cm p
410 which defaults to
411 .Cm O ,
412 .Cm a , m ,
413 and
414 .Cm c
415 which default to
416 .Cm D ,
417 and
418 .Cm Y , T ,
419 and
420 .Cm N
421 which default to
422 .Cm S .
423 .Sh EXAMPLES
424 Given a symbolic link
425 .Pa foo
426 that points from
427 .Pa /tmp/foo
428 to
429 .Pa / ,
430 you would use
431 .Nm
432 as follows:
433 .Bd -literal -offset indent
434 \*[Gt] stat -F /tmp/foo
435 lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] /
436
437 \*[Gt] stat -LF /tmp/foo
438 drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
439 .Ed
440 .Pp
441 To initialize some shell variables, you could use the
442 .Fl s
443 flag as follows:
444 .Bd -literal -offset indent
445 \*[Gt] csh
446 % eval set `stat -s .cshrc`
447 % echo $st_size $st_mtimespec
448 1148 1015432481
449
450 \*[Gt] sh
451 $ eval $(stat -s .profile)
452 $ echo $st_size $st_mtimespec
453 1148 1015432481
454 .Ed
455 .Pp
456 In order to get a list of the kind of files including files pointed to if the
457 file is a symbolic link, you could use the following format:
458 .Bd -literal -offset indent
459 $ stat -f "%N: %HT%SY" /tmp/*
460 /tmp/bar: Symbolic Link -\*[Gt] /tmp/foo
461 /tmp/output25568: Regular File
462 /tmp/blah: Directory
463 /tmp/foo: Symbolic Link -\*[Gt] /
464 .Ed
465 .Pp
466 In order to get a list of the devices, their types and the major and minor
467 device numbers, formatted with tabs and linebreaks, you could use the
468 following format:
469 .Bd -literal -offset indent
470 stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
471 [...]
472 Name: /dev/wt8
473         Type: Block Device
474         Major: 3
475         Minor: 8
476
477 Name: /dev/zero
478         Type: Character Device
479         Major: 2
480         Minor: 12
481 .Ed
482 .Pp
483 In order to determine the permissions set on a file separately, you could use
484 the following format:
485 .Bd -literal -offset indent
486 \*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" .
487 drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x
488 .Ed
489 .Pp
490 In order to determine the three files that have been modified most recently,
491 you could use the following format:
492 .Bd -literal -offset indent
493 \*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
494 Apr 25 11:47:00 2002 /tmp/blah
495 Apr 25 10:36:34 2002 /tmp/bar
496 Apr 24 16:47:35 2002 /tmp/foo
497 .Ed
498 .Sh DIAGNOSTICS
499 .Ex -std stat readlink
500 .Sh SEE ALSO
501 .Xr file 1 ,
502 .Xr ls 1 ,
503 .Xr lstat 2 ,
504 .Xr readlink 2 ,
505 .Xr stat 2 ,
506 .Xr printf 3 ,
507 .Xr strftime 3
508 .Sh HISTORY
509 The
510 .Nm
511 utility appeared in
512 .Nx 1.6
513 and
514 .Fx 4.10 .
515 .Sh AUTHORS
516 .An -nosplit
517 The
518 .Nm
519 utility was written by
520 .An Andrew Brown
521 .Aq atatat@NetBSD.org .
522 This man page was written by
523 .An Jan Schaumann
524 .Aq jschauma@NetBSD.org .