1 .\" $NetBSD: stat.1,v 1.5 2002/07/08 18:48:42 atatat Exp $
3 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Andrew Brown and Jan Schaumann.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
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.
45 .Nd display file status
64 utility displays information about the file pointed to by
66 Read, write or execute permissions of the named file are not required, but
67 all directories listed in the path name leading to the file must be
68 searchable. If no argument is given,
70 displays information about the file descriptor for standard input.
74 only the target of the symbolic link is printed. If the given argument
75 is not a symbolic link,
77 will print nothing and exit with an error.
79 The information displayed is obtained by calling
81 with the given argument and evaluating the returned structure.
83 The options are as follows:
88 display a slash (/) immediately after each pathname that is a directory, an
89 asterisk (*) after each that is executable, an at sign (@) after each symbolic
90 link, a percent sign (%) after each whiteout, an equal sign (=) after each
91 socket, and a vertical bar (|) after each that is a FIFO. The use of
100 The information reported by
102 will refer to the target of
104 if file is a symbolic link, and not to
108 Do not force a newline to appear at the end of each piece of output.
110 Suppress failure messages if calls to
117 error messages are automatically suppressed.
119 Display information using the specified format. See the FORMATS section
120 for a description of valid formats.
126 Display raw information. That is, for all the fields in the stat-structure,
127 display the raw, numerical value (for example, times in seconds since the
130 Display information in ``shell output'', suitable for initializing variables.
132 Display information in a more verbose way as known from some Linux
135 Display timestamps using the specified format. This format is
140 Format strings are similar to
142 formats in that they start with
144 are then followed by a sequence of formatting characters, and end in
145 a character that selects the field of the struct stat which is to be
148 is immediately followed by one of
154 then a newline character, a tab character, a percent character,
155 or the current file number is printed, otherwise the string is
156 examined for the following:
158 Any of the following optional flags:
161 Selects an alternate output form for octal and hexadecimal output.
162 Non-zero octal output will have a leading zero, and non-zero
163 hexadecimal output will have ``0x'' prepended to it.
165 Asserts that a sign indicating whether a number is positive or negative
166 should always be printed. Non-negative numbers are not usually printed
169 Aligns string output to the left of the field, instead of to the right.
171 Sets the fill character for left padding to the 0 character, instead of
174 Reserves a space at the front of non-negative signed output fields. A
176 overrides a space if both are used.
179 Then the following fields:
182 An optional decimal digit string specifying the minimum field width.
184 An optional precision composed of a decimal point
186 and a decimal digit string that indicates the maximum string length,
187 the number of digits to appear after the decimal point in floating point
188 output, or the minimum number of digits to appear in numeric output.
190 An optional output format specifier which is one of
198 These represent signed decimal output, octal output, unsigned decimal
199 output, hexadecimal output, floating point output, and string output,
200 respectively. Some output formats do not apply to all fields.
201 Floating point output only applies to timespec fields (the
208 The special output specifier
210 may be used to indicate that the output, if
211 applicable, should be in string format. May be used in combination with
214 Display date in strftime(3) format.
216 Display actual device name.
218 Display group or user name.
231 Insert a `` -\*[Gt] '' into the output. Note that the default output format
234 is a string, but if specified explicitly, these four characters are
238 An optional sub field specifier (high, middle, low). Only applies to
245 output formats. It can be one of the following:
248 ``High'' -- specifies the major number for devices from
252 the ``user'' bits for permissions from the string form of
254 the file ``type'' bits from the numeric forms of
256 and the long output form of
259 ``Low'' -- specifies the minor number for devices from
263 the ``other'' bits for permissions from the string form of
265 the ``user'', ``group'', and ``other'' bits from the numeric forms of
269 style output character for file type when used with
273 for this is optional).
275 ``Middle'' -- specifies the ``group'' bits for permissions from the
276 string output form of
278 or the ``suid'', ``sgid'', and ``sticky'' bits for the numeric forms of
282 A required field specifier, being one of the following:
292 File type and permissions.
294 Number of hard links to
297 User-id and group-id of
301 Device number for character and block device special files.
305 was last accessed, modified, or of when the inode was last changed.
311 Number of blocks allocated for
314 Optimal file system I/O operation block size.
316 User defined flags for
319 Inode generation number.
322 The following four field specifiers are not drawn directly from the
323 data in struct stat, but are
326 The name of the file.
328 The file type, either as in
330 or in a more descriptive form if the sub field specifier
334 The target of a symbolic link.
336 Expands to ``major,minor'' from the rdev field for character or block
337 special devices and gives size output for all others.
343 and the field specifier are required. Most field
344 specifiers default to
346 as an output form, with the
364 exits 0 on success, and \*[Gt]0 if an error occurred.
366 Given a symbolic link ``foo'' that points from /tmp/foo to /, you would use
369 .Bd -literal -offset indent
370 \*[Gt] stat -F /tmp/foo
371 lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] /
373 \*[Gt] stat -LF /tmp/foo
374 lrwxrwxrwx 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
377 To initialize some shell-variables, you could use the
380 .Bd -literal -offset indent
382 % eval set `stat -s .cshrc`
383 % echo $st_size $st_mtimespec
387 $ eval $(stat -s .profile)
388 $ echo $st_size $st_mtimespec
392 In order to get a list of the kind of files including files pointed to if the
393 file is a symbolic link, you could use the following format:
394 .Bd -literal -offset indent
395 $ stat -f "%N: %HT%SY" /tmp/*
396 /tmp/bar: Symbolic Link -\*[Gt] /tmp/foo
397 /tmp/output25568: Regular File
399 /tmp/foo: Symbolic Link -\*[Gt] /
402 In order to get a list of the devices, their types and the major and minor
403 device numbers, formatted with tabs and linebreaks, you could use the
405 .Bd -literal -offset indent
406 stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
414 Type: Character Device
419 In order to determine the permissions set on a file separately, you could use
420 the following format:
421 .Bd -literal -offset indent
422 \*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" .
423 drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x
426 In order to determine the three files that have been modified most recently,
427 you could use the following format:
428 .Bd -literal -offset indent
429 \*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
430 Apr 25 11:47:00 2002 /tmp/blah
431 Apr 25 10:36:34 2002 /tmp/bar
432 Apr 24 16:47:35 2002 /tmp/foo
450 utility was written by Andrew Brown
451 .Aq atatat@netbsd.org .
453 was written by Jan Schaumann
454 .Aq jschauma@netbsd.org .