| blob | 13189a300ac8eea50a2f0dd8e75e24a59524cf37 |
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 EXIT STATUS
424 .Ex -std stat readlink
425 .Sh EXAMPLES
426 Given a symbolic link
427 .Pa foo
428 that points from
429 .Pa /tmp/foo
430 to
431 .Pa / ,
432 you would use
433 .Nm
434 as follows:
435 .Bd -literal -offset indent
436 \*[Gt] stat -F /tmp/foo
437 lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] /
439 \*[Gt] stat -LF /tmp/foo
440 drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
441 .Ed
442 .Pp
443 To initialize some shell variables, you could use the
444 .Fl s
445 flag as follows:
446 .Bd -literal -offset indent
447 \*[Gt] csh
448 % eval set `stat -s .cshrc`
449 % echo $st_size $st_mtimespec
450 1148 1015432481
452 \*[Gt] sh
453 $ eval $(stat -s .profile)
454 $ echo $st_size $st_mtimespec
455 1148 1015432481
456 .Ed
457 .Pp
458 In order to get a list of the kind of files including files pointed to if the
459 file is a symbolic link, you could use the following format:
460 .Bd -literal -offset indent
461 $ stat -f "%N: %HT%SY" /tmp/*
462 /tmp/bar: Symbolic Link -\*[Gt] /tmp/foo
463 /tmp/output25568: Regular File
464 /tmp/blah: Directory
465 /tmp/foo: Symbolic Link -\*[Gt] /
466 .Ed
467 .Pp
468 In order to get a list of the devices, their types and the major and minor
469 device numbers, formatted with tabs and linebreaks, you could use the
470 following format:
471 .Bd -literal -offset indent
472 stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
473 [...]
474 Name: /dev/wt8
475 Type: Block Device
476 Major: 3
477 Minor: 8
479 Name: /dev/zero
480 Type: Character Device
481 Major: 2
482 Minor: 12
483 .Ed
484 .Pp
485 In order to determine the permissions set on a file separately, you could use
486 the following format:
487 .Bd -literal -offset indent
488 \*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" .
489 drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x
490 .Ed
491 .Pp
492 In order to determine the three files that have been modified most recently,
493 you could use the following format:
494 .Bd -literal -offset indent
495 \*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
496 Apr 25 11:47:00 2002 /tmp/blah
497 Apr 25 10:36:34 2002 /tmp/bar
498 Apr 24 16:47:35 2002 /tmp/foo
499 .Ed
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 .