bin/stat/stat.1

   1 .\"     $NetBSD: stat.1,v 1.40 2017/09/20 08:57:02 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2002-2011 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 November 15, 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 FLnq
  40 .Oo
  41 .Fl f Ar format |
  42 .Fl l |
  43 .Fl r |
  44 .Fl s |
  45 .Fl x
  46 .Oc
  47 .Op Fl t Ar timefmt
  48 .Op Ar
  49 .Nm readlink
  50 .Op Fl fnqsv
  51 .Op Ar
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 utility displays information about the file pointed to by
  56 .Ar file .
  57 Read, write, or execute permissions of the named file are not required, but
  58 all directories listed in the pathname leading to the file must be
  59 searchable.
  60 If no argument is given,
  61 .Nm
  62 displays information about the file descriptor for standard input.
  63 .Pp
  64 When invoked as
  65 .Nm readlink ,
  66 only the target of the symbolic link is printed.
  67 If the given argument is not a symbolic link and the
  68 .Fl f
  69 option is not specified,
  70 .Nm readlink
  71 will print nothing and exit with an error.
  72 If the
  73 .Fl f
  74 option is specified, the output is canonicalized by following every symlink
  75 in every component of the given path recursively.
  76 .Nm readlink
  77 will resolve both absolute and relative paths, and return the absolute pathname
  78 corresponding to
  79 .Ar file .
  80 In this case, the argument does not need to be a symbolic link.
  81 .Pp
  82 The information displayed is obtained by calling
  83 .Xr lstat 2
  84 with the given argument and evaluating the returned structure.
  85 The default format displays the
  86 .Fa st_dev ,
  87 .Fa st_ino ,
  88 .Fa st_mode ,
  89 .Fa st_nlink ,
  90 .Fa st_uid ,
  91 .Fa st_gid ,
  92 .Fa st_rdev ,
  93 .Fa st_size ,
  94 .Fa st_atime ,
  95 .Fa st_mtime ,
  96 .Fa st_ctime ,
  97 .Fa st_birthtime ,
  98 .Fa st_blksize ,
  99 and
 100 .Fa st_blocks
 101 fields, in that order.
 102 .Pp
 103 The options are as follows:
 104 .Bl -tag -width XFXformatXXX
 105 .It Fl F
 106 As in
 107 .Xr ls 1 ,
 108 display a slash
 109 .Pq Sq /
 110 immediately after each pathname that is a directory, an
 111 asterisk
 112 .Pq Sq *
 113 after each that is executable, an at sign
 114 .Pq Sq @
 115 after each symbolic link, a percent sign
 116 .Pq Sq %
 117 after each whiteout, an equal sign
 118 .Pq Sq =
 119 after each socket, and a vertical bar
 120 .Pq Sq \&|
 121 after each that is a FIFO.
 122 The use of
 123 .Fl F
 124 implies
 125 .Fl l .
 126 .It Fl f Ar format
 127 Display information using the specified format.
 128 See the
 129 .Sx FORMATS
 130 section for a description of valid formats.
 131 .It Fl L
 132 Use
 133 .Xr stat 2
 134 instead of
 135 .Xr lstat 2 .
 136 The information reported by
 137 .Nm
 138 will refer to the target of
 139 .Ar file ,
 140 if file is a symbolic link, and not to
 141 .Ar file
 142 itself.
 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 r
 159 Display raw information.
 160 That is, for all the fields in the stat-structure,
 161 display the raw, numerical value (for example, times in seconds since the
 162 epoch, etc.)
 163 .It Fl s
 164 Display information in
 165 .Dq shell output ,
 166 suitable for initializing variables.
 167 When run as
 168 .Nm readlink ,
 169 suppress error messages.
 170 This is equivalent to specifying
 171 .Bd -literal
 172 FMT="st_dev=%d st_ino=%i st_mode=%#p st_nlink=%l st_uid=%u st_gid=%g"
 173 FMT="$FMT st_rdev=%r st_size=%z st_atime=%Sa st_mtime=%Sm st_ctime=%Sc"
 174 FMT="$FMT st_birthtime=%SB st_blksize=%k st_blocks=%b"
 175 stat -t %s -f "$FMT" .
 176 .Ed
 177 Note that if you use a timeformat that contains embedded whitespace or shell
 178 meta-characters you will need to include appropriate quoting so the
 179 .Fl s
 180 output remains valid.
 181 .It Fl t Ar timefmt
 182 Display timestamps using the specified format.
 183 This format is
 184 passed directly to
 185 .Xr strftime 3
 186 with the extension that %f prints nanoseconds if available.
 187 .It Fl v
 188 Turn off quiet mode.
 189 .It Fl x
 190 Display information in a more verbose way as known from some Linux
 191 distributions.
 192 .El
 193 .Ss FORMATS
 194 Format strings are similar to
 195 .Xr printf 3
 196 formats in that they start with
 197 .Cm % ,
 198 are then followed by a sequence of formatting characters, and end in
 199 a character that selects the field of the struct stat which is to be
 200 formatted.
 201 If the
 202 .Cm %
 203 is immediately followed by one of
 204 .Cm n ,
 205 .Cm t ,
 206 .Cm % ,
 207 or
 208 .Cm @ ,
 209 then a newline character, a tab character, a percent character,
 210 or the current file number is printed, otherwise the string is
 211 examined for the following:
 212 .Pp
 213 Any of the following optional flags:
 214 .Bl -tag -width Ds
 215 .It Cm #
 216 Selects an alternate output form for string, octal and hexadecimal output.
 217 String output will be encoded in
 218 .Xr vis 3
 219 style.
 220 Non-zero octal output will have a leading zero.
 221 Non-zero hexadecimal output will have
 222 .Dq 0x
 223 prepended to it.
 224 .It Cm +
 225 Asserts that a sign indicating whether a number is positive or negative
 226 should always be printed.
 227 Non-negative numbers are not usually printed with a sign.
 228 .It Cm -
 229 Aligns string output to the left of the field, instead of to the right.
 230 .It Cm 0
 231 Sets the fill character for left padding to the 0 character, instead of
 232 a space.
 233 .It space
 234 Reserves a space at the front of non-negative signed output fields.
 235 A
 236 .Sq Cm +
 237 overrides a space if both are used.
 238 .El
 239 .Pp
 240 Then the following fields:
 241 .Bl -tag -width Ds
 242 .It Cm size
 243 An optional decimal digit string specifying the minimum field width.
 244 .It Cm prec
 245 An optional precision composed of a decimal point
 246 .Sq Cm \&.
 247 and a decimal digit string that indicates the maximum string length,
 248 the number of digits to appear after the decimal point in floating point
 249 output, or the minimum number of digits to appear in numeric output.
 250 .It Cm fmt
 251 An optional output format specifier which is one of
 252 .Cm D ,
 253 .Cm O ,
 254 .Cm U ,
 255 .Cm X ,
 256 .Cm F ,
 257 or
 258 .Cm S .
 259 These represent signed decimal output, octal output, unsigned decimal
 260 output, hexadecimal output, floating point output, and string output,
 261 respectively.
 262 Some output formats do not apply to all fields.
 263 Floating point output only applies to timespec fields (the
 264 .Cm a ,
 265 .Cm m ,
 266 and
 267 .Cm c
 268 fields).
 269 .Pp
 270 The special output specifier
 271 .Cm S
 272 may be used to indicate that the output, if
 273 applicable, should be in string format.
 274 May be used in combination with
 275 .Bl -tag -width Ds
 276 .It Cm amc
 277 Display date in
 278 .Xr strftime 3
 279 format with the extension that %f prints nanoseconds if available.
 280 .It Cm dr
 281 Display actual device name.
 282 .It Cm gu
 283 Display group or user name.
 284 .It Cm p
 285 Display the mode of
 286 .Ar file
 287 as in
 288 .Ic ls -led .
 289 .It Cm N
 290 Displays the name of
 291 .Ar file .
 292 .It Cm T
 293 Displays the type of
 294 .Ar file .
 295 .It Cm Y
 296 Insert a `` -> '' into the output.
 297 Note that the default output format for
 298 .Cm Y
 299 is a string, but if specified explicitly, these four characters are
 300 prepended.
 301 .El
 302 .It Cm sub
 303 An optional sub field specifier (high, middle, or low).
 304 Only applies to the
 305 .Cm p ,
 306 .Cm d ,
 307 .Cm r ,
 308 .Cm T ,
 309 .Cm N ,
 310 and
 311 .Cm z
 312 output formats.
 313 It can be one of the following:
 314 .Bl -tag -width Ds
 315 .It Cm H
 316 .Dq High
 317 -- depending on the
 318 .Cm datum :
 319 .Bl -tag -compact -width door
 320 .It Cm d , r
 321 Major number for devices
 322 .It Cm p
 323 .Dq User
 324 bits from the string form of permissions or the file
 325 .Dq type
 326 bits from the numeric forms
 327 .It Cm T
 328 The long output form of file type
 329 .It Cm N
 330 Directory path of the file, similar to what
 331 .Xr dirname 1
 332 would show
 333 .It Cm z
 334 File size, rounded to the nearest gigabyte
 335 .El
 336 .It Cm M
 337 .Dq Middle
 338 -- depending on the
 339 .Cm datum :
 340 .Bl -tag -compact -width door
 341 .It Cm p
 342 The
 343 .Dq group
 344 bits from the string form of permissions or the
 345 .Dq suid ,
 346 .Dq sgid ,
 347 and
 348 .Dq sticky
 349 bits from the numeric forms
 350 .It Cm z
 351 File size, rounded to the nearest megabyte
 352 .El
 353 .It Cm L
 354 .Dq Low
 355 -- depending on the
 356 .Cm datum :
 357 .Bl -tag -compact -width door
 358 .It Cm r , d
 359 Minor number for devices
 360 .It Cm p
 361 The
 362 .Dq other
 363 bits from the string form of permissions or the
 364 .Dq user ,
 365 .Dq group ,
 366 and
 367 .Dq other
 368 bits from the numeric forms
 369 .It Cm T
 370 The
 371 .Ic ls -F
 372 style output character for file type (the use of
 373 .Cm L
 374 here is optional)
 375 .It Cm N
 376 Base filename of the file, similar to what
 377 .Xr basename 1
 378 would show
 379 .It Cm z
 380 File size, rounded to the nearest kilobyte
 381 .El
 382 .El
 383 .It Cm datum
 384 A required field specifier, being one of the following:
 385 .Bl -tag -width 11n
 386 .It Cm d
 387 Device upon which
 388 .Ar file
 389 resides
 390 .Pq Fa st_dev .
 391 .It Cm i
 392 .Ar file Ap s
 393 inode number
 394 .Pq Fa st_ino .
 395 .It Cm p
 396 File type and permissions
 397 .Pq Fa st_mode .
 398 .It Cm l
 399 Number of hard links to
 400 .Ar file
 401 .Pq Fa st_nlink .
 402 .It Cm u , g
 403 User-id and group-id of
 404 .Ar file Ap s
 405 owner
 406 .Pq Fa st_uid , st_gid .
 407 .It Cm r
 408 Device number for character and block device special files
 409 .Pq Fa st_rdev .
 410 .It Cm a , m , c , B
 411 The time
 412 .Ar file
 413 was last accessed or modified, or when the inode was last changed, or
 414 the birth time of the inode
 415 .Pq Fa st_atime , st_mtime , st_ctime , st_birthtime .
 416 .It Cm z
 417 The size of
 418 .Ar file
 419 in bytes
 420 .Pq Fa st_size .
 421 .It Cm b
 422 Number of blocks allocated for
 423 .Ar file
 424 .Pq Fa st_blocks .
 425 .It Cm k
 426 Optimal file system I/O operation block size
 427 .Pq Fa st_blksize .
 428 .El
 429 .Pp
 430 The following five field specifiers are not drawn directly from the
 431 data in struct stat, but are:
 432 .Bl -tag -width Ds
 433 .It Cm N
 434 The name of the file.
 435 .It Cm R
 436 The absolute pathname corresponding to the file.
 437 .It Cm T
 438 The file type, either as in
 439 .Ic ls -F
 440 or in a more descriptive form if the sub field specifier
 441 .Cm H
 442 is given.
 443 .It Cm Y
 444 The target of a symbolic link.
 445 .It Cm Z
 446 Expands to
 447 .Dq Ar major , Ns Ar minor
 448 from the rdev field for character or block
 449 special devices and gives size output for all others.
 450 .El
 451 .El
 452 .Pp
 453 Only the
 454 .Cm %
 455 and the field specifier are required.
 456 Most field specifiers default to
 457 .Cm U
 458 as an output form, with the
 459 exception of
 460 .Cm p
 461 which defaults to
 462 .Cm O ;
 463 .Cm a , m ,
 464 and
 465 .Cm c
 466 which default to
 467 .Cm D ;
 468 and
 469 .Cm Y , T ,
 470 and
 471 .Cm N ,
 472 which default to
 473 .Cm S .
 474 .Sh EXIT STATUS
 475 .Ex -std
 476 .Sh EXAMPLES
 477 If no options are specified, the default format is
 478 "%d %i %Sp %l %Su %Sg %r %z \e"%Sa\e" \e"%Sm\e" \e"%Sc\e" \e"%SB\e" %k %b %#Xf %N".
 479 .Bd -literal -offset indent
 480 > stat /tmp/bar
 481 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
 482 .Ed
 483 .Pp
 484 This example produces output very similar to that from
 485 .Ic find ... -ls
 486 (except that
 487 .Xr find 1
 488 displays the time in a different format, and
 489 .Xr find 1
 490 sometimes adds one or more spaces after the comma in
 491 .Dq Ar major , Ns Ar minor
 492 for device nodes):
 493 .Bd -literal -offset indent
 494 > stat -f "%7i %6b %-11Sp %3l %-17Su %-17Sg %9Z %Sm %N%SY" /tmp/bar
 495   78852      0 -rw-r--r--    1 root              wheel                     0 Jul  8 10:26:03 2004 /tmp/bar
 496
 497 > find /tmp/bar -ls -exit
 498   78852      0 -rw-r--r--    1 root              wheel                     0 Jul  8  2004 /tmp/bar
 499 .Ed
 500 .Pp
 501 This example produces output very similar to that from
 502 .Ic ls -led
 503 (except that
 504 .Xr ls 1
 505 adjusts the column spacing differently when listing multiple files,
 506 and
 507 .Xr ls 1
 508 adds at least one space after the comma in
 509 .Dq Ar major , Ns Ar minor
 510 for device nodes):
 511 .Bd -literal -offset indent
 512 > stat -f "%-11Sp %l %Su  %Sg  %Z %Sm %N%SY" /tmp/bar
 513 -rw-r--r--  1 root  wheel  0 Jul  8 10:26:03 2004 /tmp/bar
 514
 515 > ls -led /tmp/bar
 516 -rw-r--r--  1 root  wheel  0 Jul  8 10:26:03 2004 /tmp/bar
 517 .Ed
 518 .Pp
 519 Given a symbolic link
 520 .Dq foo
 521 that points from
 522 .Pa /tmp/foo
 523 to
 524 .Pa / ,
 525 you would use
 526 .Nm
 527 as follows:
 528 .Bd -literal -offset indent
 529 > stat -F /tmp/foo
 530 lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -> /
 531
 532 > stat -LF /tmp/foo
 533 drwxr-xr-x 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
 534 .Ed
 535 .Pp
 536 To initialize some shell-variables, you could use the
 537 .Fl s
 538 flag as follows:
 539 .Bd -literal -offset indent
 540 > csh
 541 % eval set `stat -s .cshrc`
 542 % echo $st_size $st_mtime
 543 1148 1015432481
 544
 545 > sh
 546 $ eval $(stat -s .profile)
 547 $ echo $st_size $st_mtime
 548 1148 1015432481
 549 .Ed
 550 .Pp
 551 In order to get a list of the kind of files including files pointed to if the
 552 file is a symbolic link, you could use the following format:
 553 .Bd -literal -offset indent
 554 $ stat -f "%N: %HT%SY" /tmp/*
 555 /tmp/bar: Symbolic Link -> /tmp/foo
 556 /tmp/output25568: Regular File
 557 /tmp/blah: Directory
 558 /tmp/foo: Symbolic Link -> /
 559 .Ed
 560 .Pp
 561 In order to get a list of the devices, their types and the major and minor
 562 device numbers, formatted with tabs and linebreaks, you could use the
 563 following format:
 564 .Bd -literal -offset indent
 565 stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
 566 [...]
 567 Name: /dev/wt8
 568         Type: Block Device
 569         Major: 3
 570         Minor: 8
 571
 572 Name: /dev/zero
 573         Type: Character Device
 574         Major: 2
 575         Minor: 12
 576 .Ed
 577 .Pp
 578 In order to determine the permissions set on a file separately, you could use
 579 the following format:
 580 .Bd -literal -offset indent
 581 > stat -f "%Sp -> owner=%SHp group=%SMp other=%SLp" .
 582 drwxr-xr-x -> owner=rwx group=r-x other=r-x
 583 .Ed
 584 .Pp
 585 In order to determine the three files that have been modified most recently,
 586 you could use the following format:
 587 .Bd -literal -offset indent
 588 > stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
 589 Apr 25 11:47:00 2002 /tmp/blah
 590 Apr 25 10:36:34 2002 /tmp/bar
 591 Apr 24 16:47:35 2002 /tmp/foo
 592 .Ed
 593 .Pp
 594 User names, group names, and file names that contain spaces
 595 or other special characters may be encoded in
 596 .Xr vis 3
 597 style, using the
 598 .Cm \&#
 599 modifier:
 600 .Bd -literal -offset indent
 601 > ln -s 'target with spaces' 'link with spaces'
 602 > stat -f "%#N%#SY" 'link with spaces'
 603 link\eswith\esspaces -> target\eswith\esspaces
 604 .Ed
 605 .Sh SEE ALSO
 606 .Xr basename 1 ,
 607 .Xr dirname 1 ,
 608 .Xr file 1 ,
 609 .Xr ls 1 ,
 610 .Xr lstat 2 ,
 611 .Xr readlink 2 ,
 612 .Xr stat 2 ,
 613 .Xr printf 3 ,
 614 .Xr strftime 3
 615 .Sh HISTORY
 616 The
 617 .Nm
 618 utility appeared in
 619 .Nx 1.6 .
 620 .Sh AUTHORS
 621 .An -nosplit
 622 The
 623 .Nm
 624 utility was written by
 625 .An Andrew Brown
 626 .Aq atatat@NetBSD.org .
 627 This man page was written by
 628 .An Jan Schaumann
 629 .Aq jschauma@NetBSD.org .