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