usr.bin/stat/stat.1

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