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 .\" $FreeBSD: head/usr.bin/stat/stat.1 267773 2014-06-23 08:23:05Z bapt $
  31 .\"
  32 .Dd February 28, 2016
  33 .Dt STAT 1
  34 .Os
  35 .Sh NAME
  36 .Nm stat ,
  37 .Nm readlink
  38 .Nd display file status
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Op Fl FHLnq
  42 .Op Fl f Ar format | Fl l | r | s | x
  43 .Op Fl t Ar timefmt
  44 .Op Ar
  45 .Nm readlink
  46 .Op Fl fn
  47 .Op Ar
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 utility displays information about the file pointed to by
  52 .Ar file .
  53 Read, write, or execute permissions of the named file are not required, but
  54 all directories listed in the pathname leading to the file must be
  55 searchable.
  56 If no argument is given,
  57 .Nm
  58 displays information about the file descriptor for standard input.
  59 .Pp
  60 When invoked as
  61 .Nm readlink ,
  62 only the target of the symbolic link is printed.
  63 If the given argument is not a symbolic link and the
  64 .Fl f
  65 option is not specified,
  66 .Nm readlink
  67 will print nothing and exit with an error.
  68 If the
  69 .Fl f
  70 option is specified, the output is canonicalized by following every symlink
  71 in every component of the given path recursively.
  72 .Nm readlink
  73 will resolve both absolute and relative paths, and return the absolute pathname
  74 corresponding to
  75 .Ar file .
  76 In this case, the argument does not need to be a symbolic link.
  77 .Pp
  78 The information displayed is obtained by calling
  79 .Xr lstat 2
  80 with the given argument and evaluating the returned structure.
  81 The default format displays the
  82 .Fa st_dev ,
  83 .Fa st_ino ,
  84 .Fa st_mode ,
  85 .Fa st_nlink ,
  86 .Fa st_uid ,
  87 .Fa st_gid ,
  88 .Fa st_rdev ,
  89 .Fa st_size ,
  90 .Fa st_atime ,
  91 .Fa st_mtime ,
  92 .Fa st_ctime ,
  93 .Fa st_blksize ,
  94 .Fa st_blocks ,
  95 and
  96 .Fa st_flags
  97 fields, in that order.
  98 .Pp
  99 The options are as follows:
 100 .Bl -tag -width indent
 101 .It Fl F
 102 As in
 103 .Xr ls 1 ,
 104 display a slash
 105 .Pq Ql /
 106 immediately after each pathname that is a directory,
 107 an asterisk
 108 .Pq Ql *
 109 after each that is executable,
 110 an at sign
 111 .Pq Ql @
 112 after each symbolic link,
 113 a percent sign
 114 .Pq Ql %
 115 after each whiteout,
 116 an equal sign
 117 .Pq Ql =
 118 after each socket,
 119 and a vertical bar
 120 .Pq Ql |
 121 after each that is a FIFO.
 122 The use of
 123 .Fl F
 124 implies
 125 .Fl l .
 126 .It Fl H
 127 Treat each argument as the hexadecimal representation of an NFS file handle,
 128 and use
 129 .Xr fhstat 2
 130 instead of
 131 .Xr lstat 2 .
 132 This requires root privileges.
 133 .It Fl L
 134 Use
 135 .Xr stat 2
 136 instead of
 137 .Xr lstat 2 .
 138 The information reported by
 139 .Nm
 140 will refer to the target of
 141 .Ar file ,
 142 if file is a symbolic link, and not to
 143 .Ar file
 144 itself.
 145 If the link is broken or the target does not exist,
 146 fall back on
 147 .Xr lstat 2
 148 and report information about the link.
 149 .It Fl n
 150 Do not force a newline to appear at the end of each piece of output.
 151 .It Fl q
 152 Suppress failure messages if calls to
 153 .Xr stat 2
 154 or
 155 .Xr lstat 2
 156 fail.
 157 When run as
 158 .Nm readlink ,
 159 error messages are automatically suppressed.
 160 .It Fl f Ar format
 161 Display information using the specified format.
 162 See the
 163 .Sx Formats
 164 section for a description of valid formats.
 165 .It Fl l
 166 Display output in
 167 .Nm ls Fl lT
 168 format.
 169 .It Fl r
 170 Display raw information.
 171 That is, for all the fields in the
 172 .Vt stat
 173 structure,
 174 display the raw, numerical value (for example, times in seconds since the
 175 epoch, etc.).
 176 .It Fl s
 177 Display information in
 178 .Dq shell output
 179 format,
 180 suitable for initializing variables.
 181 .It Fl x
 182 Display information in a more verbose way as known from some
 183 .Tn Linux
 184 distributions.
 185 .It Fl t Ar timefmt
 186 Display timestamps using the specified format.
 187 This format is
 188 passed directly to
 189 .Xr strftime 3 .
 190 .El
 191 .Ss Formats
 192 Format strings are similar to
 193 .Xr printf 3
 194 formats in that they start with
 195 .Cm % ,
 196 are then followed by a sequence of formatting characters, and end in
 197 a character that selects the field of the
 198 .Vt "struct stat"
 199 which is to be formatted.
 200 If the
 201 .Cm %
 202 is immediately followed by one of
 203 .Cm n , t , % ,
 204 or
 205 .Cm @ ,
 206 then a newline character, a tab character, a percent character,
 207 or the current file number is printed, otherwise the string is
 208 examined for the following:
 209 .Pp
 210 Any of the following optional flags:
 211 .Bl -tag -width indent
 212 .It Cm #
 213 Selects an alternate output form for octal and hexadecimal output.
 214 Non-zero octal output will have a leading zero, and non-zero
 215 hexadecimal output will have
 216 .Dq Li 0x
 217 prepended to it.
 218 .It Cm +
 219 Asserts that a sign indicating whether a number is positive or negative
 220 should always be printed.
 221 Non-negative numbers are not usually printed
 222 with a sign.
 223 .It Cm -
 224 Aligns string output to the left of the field, instead of to the right.
 225 .It Cm 0
 226 Sets the fill character for left padding to the
 227 .Ql 0
 228 character, instead of a space.
 229 .It space
 230 Reserves a space at the front of non-negative signed output fields.
 231 A
 232 .Sq Cm +
 233 overrides a space if both are used.
 234 .El
 235 .Pp
 236 Then the following fields:
 237 .Bl -tag -width indent
 238 .It Ar size
 239 An optional decimal digit string specifying the minimum field width.
 240 .It Ar prec
 241 An optional precision composed of a decimal point
 242 .Sq Cm \&.
 243 and a decimal digit string that indicates the maximum string length,
 244 the number of digits to appear after the decimal point in floating point
 245 output, or the minimum number of digits to appear in numeric output.
 246 .It Ar fmt
 247 An optional output format specifier which is one of
 248 .Cm D , O , U , X , F ,
 249 or
 250 .Cm S .
 251 These represent signed decimal output, octal output, unsigned decimal
 252 output, hexadecimal output, floating point output, and string output,
 253 respectively.
 254 Some output formats do not apply to all fields.
 255 Floating point output only applies to
 256 .Vt timespec
 257 fields (the
 258 .Cm a , m ,
 259 and
 260 .Cm c
 261 fields).
 262 .Pp
 263 The special output specifier
 264 .Cm S
 265 may be used to indicate that the output, if
 266 applicable, should be in string format.
 267 May be used in combination with:
 268 .Bl -tag -width indent
 269 .It Cm amc
 270 Display date in
 271 .Xr strftime 3
 272 format.
 273 .It Cm dr
 274 Display actual device name.
 275 .It Cm f
 276 Display the flags of
 277 .Ar file
 278 as in
 279 .Nm ls Fl lTdo .
 280 .It Cm gu
 281 Display group or user name.
 282 .It Cm p
 283 Display the mode of
 284 .Ar file
 285 as in
 286 .Nm ls Fl lTd .
 287 .It Cm N
 288 Displays the name of
 289 .Ar file .
 290 .It Cm T
 291 Displays the type of
 292 .Ar file .
 293 .It Cm Y
 294 Insert a
 295 .Dq Li " -\*[Gt] "
 296 into the output.
 297 Note that the default output format
 298 for
 299 .Cm Y
 300 is a string, but if specified explicitly, these four characters are
 301 prepended.
 302 .El
 303 .It Ar sub
 304 An optional sub field specifier (high, middle, low).
 305 Only applies to
 306 the
 307 .Cm p , d , r ,
 308 and
 309 .Cm T
 310 output formats.
 311 It can be one of the following:
 312 .Bl -tag -width indent
 313 .It Cm H
 314 .Dq High
 315 \[em]
 316 specifies the major number for devices from
 317 .Cm r
 318 or
 319 .Cm d ,
 320 the
 321 .Dq user
 322 bits for permissions from the string form of
 323 .Cm p ,
 324 the file
 325 .Dq type
 326 bits from the numeric forms of
 327 .Cm p ,
 328 and the long output form of
 329 .Cm T .
 330 .It Cm L
 331 .Dq Low
 332 \[em]
 333 specifies the minor number for devices from
 334 .Cm r
 335 or
 336 .Cm d ,
 337 the
 338 .Dq other
 339 bits for permissions from the string form of
 340 .Cm p ,
 341 the
 342 .Dq user ,
 343 .Dq group ,
 344 and
 345 .Dq other
 346 bits from the numeric forms of
 347 .Cm p ,
 348 and the
 349 .Nm ls Fl F
 350 style output character for file type when used with
 351 .Cm T
 352 (the use of
 353 .Cm L
 354 for this is optional).
 355 .It Cm M
 356 .Dq Middle
 357 \[em]
 358 specifies the
 359 .Dq group
 360 bits for permissions from the
 361 string output form of
 362 .Cm p ,
 363 or the
 364 .Dq suid ,
 365 .Dq sgid ,
 366 and
 367 .Dq sticky
 368 bits for the numeric forms of
 369 .Cm p .
 370 .El
 371 .It Ar datum
 372 A required field specifier, being one of the following:
 373 .Bl -tag -width indent
 374 .It Cm d
 375 Device upon which
 376 .Ar file
 377 resides
 378 .Pq Fa st_dev .
 379 .It Cm i
 380 .Ar file Ns 's
 381 inode number
 382 .Pq Fa st_ino .
 383 .It Cm p
 384 File type and permissions
 385 .Pq Fa st_mode .
 386 .It Cm l
 387 Number of hard links to
 388 .Ar file
 389 .Pq Fa st_nlink .
 390 .It Cm u , g
 391 User ID and group ID of
 392 .Ar file Ns 's
 393 owner
 394 .Pq Fa st_uid , st_gid .
 395 .It Cm r
 396 Device number for character and block device special files
 397 .Pq Fa st_rdev .
 398 .It Cm a , m , c
 399 The time
 400 .Ar file
 401 was last accessed or modified, or when the inode was last changed
 402 .Pq Fa st_atime , st_mtime , st_ctime .
 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" %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" 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/xpt0
 532         Type: Character Device
 533         Major: 28
 534         Minor: 0
 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 .