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