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