usr.bin/stat/stat.1

   1 .\"     $NetBSD: stat.1,v 1.11 2003/05/08 13:07:10 wiz 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, 2010
  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 f
 243 Display the flags of
 244 .Ar file
 245 as in
 246 .Nm ls Fl lTdo .
 247 .It Cm gu
 248 Display group or user name.
 249 .It Cm p
 250 Display the mode of
 251 .Ar file
 252 as in
 253 .Nm ls Fl lTd .
 254 .It Cm N
 255 Displays the name of
 256 .Ar file .
 257 .It Cm T
 258 Displays the type of
 259 .Ar file .
 260 .It Cm Y
 261 Insert a
 262 .Dq Li " -\*[Gt] "
 263 into the output.
 264 Note that the default output format
 265 for
 266 .Cm Y
 267 is a string, but if specified explicitly, these four characters are
 268 prepended.
 269 .El
 270 .It Ar sub
 271 An optional sub field specifier (high, middle, low).
 272 Only applies to
 273 the
 274 .Cm p , d , r ,
 275 and
 276 .Cm T
 277 output formats.
 278 It can be one of the following:
 279 .Bl -tag -width indent
 280 .It Cm H
 281 .Dq High
 282 \[em]
 283 specifies the major number for devices from
 284 .Cm r
 285 or
 286 .Cm d ,
 287 the
 288 .Dq user
 289 bits for permissions from the string form of
 290 .Cm p ,
 291 the file
 292 .Dq type
 293 bits from the numeric forms of
 294 .Cm p ,
 295 and the long output form of
 296 .Cm T .
 297 .It Cm L
 298 .Dq Low
 299 \[em]
 300 specifies the minor number for devices from
 301 .Cm r
 302 or
 303 .Cm d ,
 304 the
 305 .Dq other
 306 bits for permissions from the string form of
 307 .Cm p ,
 308 the
 309 .Dq user ,
 310 .Dq group ,
 311 and
 312 .Dq other
 313 bits from the numeric forms of
 314 .Cm p ,
 315 and the
 316 .Nm ls Fl F
 317 style output character for file type when used with
 318 .Cm T
 319 (the use of
 320 .Cm L
 321 for this is optional).
 322 .It Cm M
 323 .Dq Middle
 324 \[em]
 325 specifies the
 326 .Dq group
 327 bits for permissions from the
 328 string output form of
 329 .Cm p ,
 330 or the
 331 .Dq suid ,
 332 .Dq sgid ,
 333 and
 334 .Dq sticky
 335 bits for the numeric forms of
 336 .Cm p .
 337 .El
 338 .It Ar datum
 339 A required field specifier, being one of the following:
 340 .Bl -tag -width indent
 341 .It Cm d
 342 Device upon which
 343 .Ar file
 344 resides.
 345 .It Cm i
 346 .Ar file Ns 's
 347 inode number.
 348 .It Cm p
 349 File type and permissions.
 350 .It Cm l
 351 Number of hard links to
 352 .Ar file .
 353 .It Cm u , g
 354 User ID and group ID of
 355 .Ar file Ns 's
 356 owner.
 357 .It Cm r
 358 Device number for character and block device special files.
 359 .It Cm a , m , c , B
 360 The time
 361 .Ar file
 362 was last accessed or modified, of when the inode was last changed, or
 363 the birth time of the inode.
 364 .It Cm z
 365 The size of
 366 .Ar file
 367 in bytes.
 368 .It Cm b
 369 Number of blocks allocated for
 370 .Ar file .
 371 .It Cm k
 372 Optimal file system I/O operation block size.
 373 .It Cm f
 374 User defined flags for
 375 .Ar file .
 376 .It Cm v
 377 Inode generation number.
 378 .El
 379 .Pp
 380 The following four field specifiers are not drawn directly from the
 381 data in
 382 .Vt "struct stat" ,
 383 but are:
 384 .Bl -tag -width indent
 385 .It Cm N
 386 The name of the file.
 387 .It Cm T
 388 The file type, either as in
 389 .Nm ls Fl F
 390 or in a more descriptive form if the
 391 .Ar sub
 392 field specifier
 393 .Cm H
 394 is given.
 395 .It Cm Y
 396 The target of a symbolic link.
 397 .It Cm Z
 398 Expands to
 399 .Dq major,minor
 400 from the
 401 .Va rdev
 402 field for character or block
 403 special devices and gives size output for all others.
 404 .El
 405 .El
 406 .Pp
 407 Only the
 408 .Cm %
 409 and the field specifier are required.
 410 Most field specifiers default to
 411 .Cm U
 412 as an output form, with the
 413 exception of
 414 .Cm p
 415 which defaults to
 416 .Cm O ,
 417 .Cm a , m ,
 418 and
 419 .Cm c
 420 which default to
 421 .Cm D ,
 422 and
 423 .Cm Y , T ,
 424 and
 425 .Cm N
 426 which default to
 427 .Cm S .
 428 .Sh EXIT STATUS
 429 .Ex -std stat readlink
 430 .Sh EXAMPLES
 431 Given a symbolic link
 432 .Pa foo
 433 that points from
 434 .Pa /tmp/foo
 435 to
 436 .Pa / ,
 437 you would use
 438 .Nm
 439 as follows:
 440 .Bd -literal -offset indent
 441 \*[Gt] stat -F /tmp/foo
 442 lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] /
 443
 444 \*[Gt] stat -LF /tmp/foo
 445 drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
 446 .Ed
 447 .Pp
 448 To initialize some shell variables, you could use the
 449 .Fl s
 450 flag as follows:
 451 .Bd -literal -offset indent
 452 \*[Gt] csh
 453 % eval set `stat -s .cshrc`
 454 % echo $st_size $st_mtimespec
 455 1148 1015432481
 456
 457 \*[Gt] sh
 458 $ eval $(stat -s .profile)
 459 $ echo $st_size $st_mtimespec
 460 1148 1015432481
 461 .Ed
 462 .Pp
 463 In order to get a list of file types including files pointed to if the
 464 file is a symbolic link, you could use the following format:
 465 .Bd -literal -offset indent
 466 $ stat -f "%N: %HT%SY" /tmp/*
 467 /tmp/bar: Symbolic Link -\*[Gt] /tmp/foo
 468 /tmp/output25568: Regular File
 469 /tmp/blah: Directory
 470 /tmp/foo: Symbolic Link -\*[Gt] /
 471 .Ed
 472 .Pp
 473 In order to get a list of the devices, their types and the major and minor
 474 device numbers, formatted with tabs and linebreaks, you could use the
 475 following format:
 476 .Bd -literal -offset indent
 477 stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
 478 [...]
 479 Name: /dev/wt8
 480         Type: Block Device
 481         Major: 3
 482         Minor: 8
 483
 484 Name: /dev/zero
 485         Type: Character Device
 486         Major: 2
 487         Minor: 12
 488 .Ed
 489 .Pp
 490 In order to determine the permissions set on a file separately, you could use
 491 the following format:
 492 .Bd -literal -offset indent
 493 \*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" .
 494 drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x
 495 .Ed
 496 .Pp
 497 In order to determine the three files that have been modified most recently,
 498 you could use the following format:
 499 .Bd -literal -offset indent
 500 \*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
 501 Apr 25 11:47:00 2002 /tmp/blah
 502 Apr 25 10:36:34 2002 /tmp/bar
 503 Apr 24 16:47:35 2002 /tmp/foo
 504 .Ed
 505 .Pp
 506 To display a file's modification time:
 507 .Bd -literal -offset indent
 508 \*[Gt] stat -f %m /tmp/foo
 509 1177697733
 510 .Ed
 511 .Pp
 512 To display the same modification time in a readable format:
 513 .Bd -literal -offset indent
 514 \*[Gt] stat -f %Sm /tmp/foo
 515 Apr 27 11:15:33 2007
 516 .Ed
 517 .Pp
 518 To display the same modification time in a readable and sortable format:
 519 .Bd -literal -offset indent
 520 \*[Gt] stat -f %Sm -t %Y%m%d%H%M%S /tmp/foo
 521 20070427111533
 522 .Ed
 523 .Pp
 524 To display the same in UTC:
 525 .Bd -literal -offset indent
 526 \*[Gt] sh
 527 $ TZ= stat -f %Sm -t %Y%m%d%H%M%S /tmp/foo
 528 20070427181533
 529 .Ed
 530 .Sh SEE ALSO
 531 .Xr file 1 ,
 532 .Xr ls 1 ,
 533 .Xr lstat 2 ,
 534 .Xr readlink 2 ,
 535 .Xr stat 2 ,
 536 .Xr printf 3 ,
 537 .Xr strftime 3
 538 .Sh HISTORY
 539 The
 540 .Nm
 541 utility appeared in
 542 .Nx 1.6
 543 and
 544 .Fx 4.10 .
 545 .Sh AUTHORS
 546 .An -nosplit
 547 The
 548 .Nm
 549 utility was written by
 550 .An Andrew Brown
 551 .Aq atatat@NetBSD.org .
 552 This man page was written by
 553 .An Jan Schaumann
 554 .Aq jschauma@NetBSD.org .