usr.bin/stat/stat.1

   1 .\"     $NetBSD: stat.1,v 1.5 2002/07/08 18:48:42 atatat Exp $
   2 .\"
   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$
  38 .\"
  39 .Dd April 24, 2002
  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 .Oo
  50 .Fl f Ar format |
  51 .Fl l |
  52 .Fl r |
  53 .Fl s |
  54 .Fl x
  55 .Oc
  56 .Op Fl t Ar timefmt
  57 .Op Ar
  58 .Nm readlink
  59 .Op Fl n
  60 .Op Ar
  61 .Sh DESCRIPTION
  62 The
  63 .Nm
  64 utility displays information about the file pointed to by
  65 .Ar file .
  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,
  69 .Nm
  70 displays information about the file descriptor for standard input.
  71 .Pp
  72 When invoked as
  73 .Nm readlink ,
  74 only the target of the symbolic link is printed.  If the given argument
  75 is not a symbolic link,
  76 .Nm readlink
  77 will print nothing and exit with an error.
  78 .Pp
  79 The information displayed is obtained by calling
  80 .Xr lstat 2
  81 with the given argument and evaluating the returned structure.
  82 .Pp
  83 The options are as follows:
  84 .Bl -tag -width Ds
  85 .It Fl F
  86 As in
  87 .Ic ls ,
  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
  92 .Fl F
  93 implies
  94 .Fl l .
  95 .It Fl L
  96 Use
  97 .Xr stat 2
  98 instead of
  99 .Xr lstat 2 .
 100 The information reported by
 101 .Nm
 102 will refer to the target of
 103 .Ar file ,
 104 if file is a symbolic link, and not to
 105 .Ar file
 106 itself.
 107 .It Fl n
 108 Do not force a newline to appear at the end of each piece of output.
 109 .It Fl q
 110 Suppress failure messages if calls to
 111 .Xr stat 2
 112 or
 113 .Xr lstat 2
 114 fail.
 115 When run as
 116 .Nm readlink ,
 117 error messages are automatically suppressed.
 118 .It Fl f Ar format
 119 Display information using the specified format.  See the FORMATS section
 120 for a description of valid formats.
 121 .It Fl l
 122 Display output in
 123 .Ic ls Fl lT
 124 format.
 125 .It Fl r
 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
 128 epoch, etc.)
 129 .It Fl s
 130 Display information in ``shell output'', suitable for initializing variables.
 131 .It Fl x
 132 Display information in a more verbose way as known from some Linux
 133 distributions.
 134 .It Fl t Ar timefmt
 135 Display timestamps using the specified format.  This format is
 136 passed directly to
 137 .Xr strftime 3 .
 138 .El
 139 .Ss FORMATS
 140 Format strings are similar to
 141 .Xr printf 3
 142 formats in that they start with
 143 .Cm % ,
 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
 146 formatted.  If the
 147 .Cm %
 148 is immediately followed by one of
 149 .Cm n ,
 150 .Cm t ,
 151 .Cm % ,
 152 or
 153 .Cm @ ,
 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:
 157 .Pp
 158 Any of the following optional flags:
 159 .Bl -tag -width Ds
 160 .It Cm #
 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.
 164 .It Cm +
 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
 167 with a sign.
 168 .It Cm -
 169 Aligns string output to the left of the field, instead of to the right.
 170 .It Cm 0
 171 Sets the fill character for left padding to the 0 character, instead of
 172 a space.
 173 .It space
 174 Reserves a space at the front of non-negative signed output fields.  A
 175 .Sq Cm +
 176 overrides a space if both are used.
 177 .El
 178 .Pp
 179 Then the following fields:
 180 .Bl -tag -width Ds
 181 .It Cm size
 182 An optional decimal digit string specifying the minimum field width.
 183 .It Cm prec
 184 An optional precision composed of a decimal point
 185 .Sq Cm \&.
 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.
 189 .It Cm fmt
 190 An optional output format specifier which is one of
 191 .Cm D ,
 192 .Cm O ,
 193 .Cm U ,
 194 .Cm X ,
 195 .Cm F ,
 196 or
 197 .Cm S .
 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
 202 .Cm a ,
 203 .Cm m ,
 204 and
 205 .Cm c
 206 fields).
 207 .Pp
 208 The special output specifier
 209 .Cm S
 210 may be used to indicate that the output, if
 211 applicable, should be in string format.  May be used in combination with
 212 .Bl -tag -width Ds
 213 .It Cm amc
 214 Display date in strftime(3) format.
 215 .It Cm dr
 216 Display actual device name.
 217 .It Cm gu
 218 Display group or user name.
 219 .It Cm p
 220 Display the mode of
 221 .Ar file
 222 as in
 223 .Ic ls -lTd .
 224 .It Cm N
 225 Displays the name of
 226 .Ar file .
 227 .It Cm T
 228 Displays the type of
 229 .Ar file .
 230 .It Cm Y
 231 Insert a `` -\*[Gt] '' into the output.  Note that the default output format
 232 for
 233 .Cm Y
 234 is a string, but if specified explicitly, these four characters are
 235 prepended.
 236 .El
 237 .It Cm sub
 238 An optional sub field specifier (high, middle, low).  Only applies to
 239 the
 240 .Cm p ,
 241 .Cm d ,
 242 .Cm r ,
 243 and
 244 .Cm T
 245 output formats.  It can be one of the following:
 246 .Bl -tag -width Ds
 247 .It Cm H
 248 ``High'' -- specifies the major number for devices from
 249 .Cm r
 250 or
 251 .Cm d ,
 252 the ``user'' bits for permissions from the string form of
 253 .Cm p ,
 254 the file ``type'' bits from the numeric forms of
 255 .Cm p ,
 256 and the long output form of
 257 .Cm T .
 258 .It Cm L
 259 ``Low'' -- specifies the minor number for devices from
 260 .Cm r
 261 or
 262 .Cm d ,
 263 the ``other'' bits for permissions from the string form of
 264 .Cm p ,
 265 the ``user'', ``group'', and ``other'' bits from the numeric forms of
 266 .Cm p ,
 267 and the
 268 .Ic ls -F
 269 style output character for file type when used with
 270 .Cm T
 271 (the use of
 272 .Cm L
 273 for this is optional).
 274 .It Cm M
 275 ``Middle'' -- specifies the ``group'' bits for permissions from the
 276 string output form of
 277 .Cm p ,
 278 or the ``suid'', ``sgid'', and ``sticky'' bits for the numeric forms of
 279 .Cm p .
 280 .El
 281 .It Cm datum
 282 A required field specifier, being one of the following:
 283 .Bl -tag -width Ds
 284 .It Cm d
 285 Device upon which
 286 .Ar file
 287 resides.
 288 .It Cm i
 289 .Ar file Ap s
 290 inode number.
 291 .It Cm p
 292 File type and permissions.
 293 .It Cm l
 294 Number of hard links to
 295 .Ar file .
 296 .It Cm u , g
 297 User-id and group-id of
 298 .Ar file Ap s
 299 owner.
 300 .It Cm r
 301 Device number for character and block device special files.
 302 .It Cm a , m , c
 303 The time
 304 .Ar file
 305 was last accessed, modified, or of when the inode was last changed.
 306 .It Cm z
 307 The size of
 308 .Ar file
 309 in bytes.
 310 .It Cm b
 311 Number of blocks allocated for
 312 .Ar file .
 313 .It Cm k
 314 Optimal file system I/O operation block size.
 315 .It Cm f
 316 User defined flags for
 317 .Ar file .
 318 .It Cm v
 319 Inode generation number.
 320 .El
 321 .Pp
 322 The following four field specifiers are not drawn directly from the
 323 data in struct stat, but are
 324 .Bl -tag -width Ds
 325 .It Cm N
 326 The name of the file.
 327 .It Cm T
 328 The file type, either as in
 329 .Ic ls -F
 330 or in a more descriptive form if the sub field specifier
 331 .Cm H
 332 is given.
 333 .It Cm Y
 334 The target of a symbolic link.
 335 .It Cm Z
 336 Expands to ``major,minor'' from the rdev field for character or block
 337 special devices and gives size output for all others.
 338 .El
 339 .El
 340 .Pp
 341 Only the
 342 .Cm %
 343 and the field specifier are required.  Most field
 344 specifiers default to
 345 .Cm U
 346 as an output form, with the
 347 exception of
 348 .Cm p
 349 which defaults to
 350 .Cm O ,
 351 .Cm a , m ,
 352 and
 353 .Cm c
 354 which default to
 355 .Cm D ,
 356 and
 357 .Cm Y , T ,
 358 and
 359 .Cm N ,
 360 which default to
 361 .Cm S .
 362 .Sh EXIT STATUS
 363 .Nm
 364 exits 0 on success, and \*[Gt]0 if an error occurred.
 365 .Sh EXAMPLES
 366 Given a symbolic link ``foo'' that points from /tmp/foo to /, you would use
 367 .Nm
 368 as follows:
 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] /
 372
 373 \*[Gt] stat -LF /tmp/foo
 374 lrwxrwxrwx 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
 375 .Ed
 376 .Pp
 377 To initialize some shell-variables, you could use the
 378 .Fl s
 379 flag as follows:
 380 .Bd -literal -offset indent
 381 \*[Gt] csh
 382 % eval set `stat -s .cshrc`
 383 % echo $st_size $st_mtimespec
 384 1148 1015432481
 385
 386 \*[Gt] sh
 387 $ eval $(stat -s .profile)
 388 $ echo $st_size $st_mtimespec
 389 1148 1015432481
 390 .Ed
 391 .Pp
 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
 398 /tmp/blah: Directory
 399 /tmp/foo: Symbolic Link -\*[Gt] /
 400 .Ed
 401 .Pp
 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
 404 following format:
 405 .Bd -literal -offset indent
 406 stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
 407 [...]
 408 Name: /dev/wt8
 409         Type: Block Device
 410         Major: 3
 411         Minor: 8
 412
 413 Name: /dev/zero
 414         Type: Character Device
 415         Major: 2
 416         Minor: 12
 417 .Ed
 418 .Pp
 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
 424 .Ed
 425 .Pp
 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
 433 .Ed
 434 .Sh SEE ALSO
 435 .Xr file 1 ,
 436 .Xr ls 1 ,
 437 .Xr lstat 2 ,
 438 .Xr readlink 2 ,
 439 .Xr stat 2 ,
 440 .Xr printf 3 ,
 441 .Xr strftime 3
 442 .Sh HISTORY
 443 The
 444 .Nm
 445 utility appeared in
 446 .Nx 1.6 .
 447 .Sh AUTHORS
 448 The
 449 .Nm
 450 utility was written by Andrew Brown
 451 .Aq atatat@netbsd.org .
 452 This man page
 453 was written by Jan Schaumann
 454 .Aq jschauma@netbsd.org .