original/man2/stat.2

   1 '\" t
   2 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   3 .\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95
   4 .\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   5 .\"
   6 .\" %%%LICENSE_START(VERBATIM)
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\" %%%LICENSE_END
  27 .\"
  28 .\" Modified by Michael Haardt <michael@moria.de>
  29 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
  30 .\" Modified 1995-05-18 by Todd Larason <jtl@molehill.org>
  31 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
  32 .\" Modified 1995-01-09 by Richard Kettlewell <richard@greenend.org.uk>
  33 .\" Modified 1998-05-13 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de>
  34 .\" Modified 1999-07-06 by aeb & Albert Cahalan
  35 .\" Modified 2000-01-07 by aeb
  36 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  37 .\" 2007-06-08 mtk: Added example program
  38 .\" 2007-07-05 mtk: Added details on underlying system call interfaces
  39 .\"
  40 .TH STAT 2 2014-05-10 "Linux" "Linux Programmer's Manual"
  41 .SH NAME
  42 stat, fstat, lstat, fstatat \- get file status
  43 .SH SYNOPSIS
  44 .nf
  45 .B #include <sys/types.h>
  46 .br
  47 .B #include <sys/stat.h>
  48 .br
  49 .B #include <unistd.h>
  50 .sp
  51 .BI "int stat(const char *" pathname ", struct stat *" buf );
  52 .br
  53 .BI "int fstat(int " fd ", struct stat *" buf );
  54 .br
  55 .BI "int lstat(const char *" pathname ", struct stat *" buf );
  56 .sp
  57 .BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
  58 .B #include <sys/stat.h>
  59 .sp
  60 .BI "int fstatat(int " dirfd ", const char *" pathname ", struct stat *" \
  61 buf ,
  62 .BI "            int " flags );
  63 .fi
  64 .sp
  65 .in -4n
  66 Feature Test Macro Requirements for glibc (see
  67 .BR feature_test_macros (7)):
  68 .in
  69 .ad l
  70 .PD 0
  71 .sp
  72 .BR lstat ():
  73 .RS 4
  74 /* glibc 2.19 and earlier */ _BSD_SOURCE ||
  75 .br
  76 /* Since glibc 2.20 */_DEFAULT_SOURCE ||
  77 .br
  78 _XOPEN_SOURCE\ >=\ 500 ||
  79 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  80 .br
  81 || /* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200112L
  82 .RE
  83 .sp
  84 .BR fstatat ():
  85 .PD 0
  86 .ad l
  87 .RS 4
  88 .TP 4
  89 Since glibc 2.10:
  90 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  91 .TP
  92 Before glibc 2.10:
  93 _ATFILE_SOURCE
  94 .RE
  95 .PD
  96 .ad
  97 .SH DESCRIPTION
  98 .PP
  99 These functions return information about a file, in the buffer pointed to by
 100 .IR stat .
 101 No permissions are required on the file itself, but\(emin the case of
 102 .BR stat (),
 103 .BR fstatat (),
 104 and
 105 .BR lstat ()\(emexecute
 106 (search) permission is required on all of the directories in
 107 .I pathname
 108 that lead to the file.
 109 .PP
 110 .BR stat ()
 111 and
 112 .BR fstatat ()
 113 retrieve information about the file pointed to by
 114 .IR pathname ;
 115 the differences for
 116 .BR fstatat ()
 117 are described below.
 118
 119 .BR lstat ()
 120 is identical to
 121 .BR stat (),
 122 except that if
 123 .I pathname
 124 is a symbolic link, then it returns information about the link itself,
 125 not the file that it refers to.
 126
 127 .BR fstat ()
 128 is identical to
 129 .BR stat (),
 130 except that the file about which information is to be retrieved
 131 is specified by the file descriptor
 132 .IR fd .
 133 .PP
 134 All of these system calls return a
 135 .I stat
 136 structure, which contains the following fields:
 137 .PP
 138 .in +4n
 139 .nf
 140 struct stat {
 141     dev_t     st_dev;         /* ID of device containing file */
 142     ino_t     st_ino;         /* inode number */
 143     mode_t    st_mode;        /* protection */
 144     nlink_t   st_nlink;       /* number of hard links */
 145     uid_t     st_uid;         /* user ID of owner */
 146     gid_t     st_gid;         /* group ID of owner */
 147     dev_t     st_rdev;        /* device ID (if special file) */
 148     off_t     st_size;        /* total size, in bytes */
 149     blksize_t st_blksize;     /* blocksize for filesystem I/O */
 150     blkcnt_t  st_blocks;      /* number of 512B blocks allocated */
 151
 152     /* Since Linux 2.6, the kernel supports nanosecond
 153        precision for the following timestamp fields.
 154        For the details before Linux 2.6, see NOTES. */
 155
 156     struct timespec st_atim;  /* time of last access */
 157     struct timespec st_mtim;  /* time of last modification */
 158     struct timespec st_ctim;  /* time of last status change */
 159
 160 #define st_atime st_atim.tv_sec      /* Backward compatibility */
 161 #define st_mtime st_mtim.tv_sec
 162 #define st_ctime st_ctim.tv_sec
 163 };
 164 .fi
 165 .in
 166
 167 .I Note:
 168 the order of fields in the
 169 .I stat
 170 structure varies somewhat
 171 across architectures.
 172 In addition,
 173 the definition above does not show the padding bytes
 174 that may be present between some fields on various architectures.
 175 Consult the the glibc and kernel source code
 176 if you need to know the details.
 177
 178 The
 179 .I st_dev
 180 field describes the device on which this file resides.
 181 (The
 182 .BR major (3)
 183 and
 184 .BR minor (3)
 185 macros may be useful to decompose the device ID in this field.)
 186
 187 The
 188 .I st_rdev
 189 field describes the device that this file (inode) represents.
 190
 191 The
 192 .I st_size
 193 field gives the size of the file (if it is a regular
 194 file or a symbolic link) in bytes.
 195 The size of a symbolic link is the length of the pathname
 196 it contains, without a terminating null byte.
 197
 198 The
 199 .I st_blocks
 200 field indicates the number of blocks allocated to the file, 512-byte units.
 201 (This may be smaller than
 202 .IR st_size /512
 203 when the file has holes.)
 204
 205 The
 206 .I st_blksize
 207 field gives the "preferred" blocksize for efficient filesystem I/O.
 208 (Writing to a file in smaller chunks may cause
 209 an inefficient read-modify-rewrite.)
 210 .PP
 211 Not all of the Linux filesystems implement all of the time fields.
 212 Some filesystem types allow mounting in such a way that file
 213 and/or directory accesses do not cause an update of the
 214 .I st_atime
 215 field.
 216 (See
 217 .IR noatime ,
 218 .IR nodiratime ,
 219 and
 220 .I relatime
 221 in
 222 .BR mount (8),
 223 and related information in
 224 .BR mount (2).)
 225 In addition,
 226 .I st_atime
 227 is not updated if a file is opened with the
 228 .BR O_NOATIME ;
 229 see
 230 .BR open (2).
 231
 232 The field
 233 .I st_atime
 234 is changed by file accesses, for example, by
 235 .BR execve (2),
 236 .BR mknod (2),
 237 .BR pipe (2),
 238 .BR utime (2)
 239 and
 240 .BR read (2)
 241 (of more than zero bytes).
 242 Other routines, like
 243 .BR mmap (2),
 244 may or may not update
 245 .IR st_atime .
 246
 247 The field
 248 .I st_mtime
 249 is changed by file modifications, for example, by
 250 .BR mknod (2),
 251 .BR truncate (2),
 252 .BR utime (2)
 253 and
 254 .BR write (2)
 255 (of more than zero bytes).
 256 Moreover,
 257 .I st_mtime
 258 of a directory is changed by the creation or deletion of files
 259 in that directory.
 260 The
 261 .I st_mtime
 262 field is
 263 .I not
 264 changed for changes in owner, group, hard link count, or mode.
 265
 266 The field
 267 .I st_ctime
 268 is changed by writing or by setting inode information
 269 (i.e., owner, group, link count, mode, etc.).
 270 .PP
 271 The following mask values are defined for the file type component of the
 272 .I st_mode
 273 field:
 274 .in +4n
 275 .TS
 276 lB l l.
 277 S_IFMT  0170000 bit mask for the file type bit fields
 278
 279 S_IFSOCK        0140000 socket
 280 S_IFLNK 0120000 symbolic link
 281 S_IFREG 0100000 regular file
 282 S_IFBLK 0060000 block device
 283 S_IFDIR 0040000 directory
 284 S_IFCHR 0020000 character device
 285 S_IFIFO 0010000 FIFO
 286 .TE
 287 .in
 288 .PP
 289 Thus, to test for a regular file (for example), one could write:
 290
 291 .nf
 292 .in +4n
 293 stat(pathname, &sb);
 294 if ((sb.st_mode & S_IFMT) == S_IFREG) {
 295     /* Handle regular file */
 296 }
 297 .in
 298 .fi
 299 .PP
 300 Because tests of the above form are common, additional
 301 macros are defined by POSIX to allow the test of the file type in
 302 .I st_mode
 303 to be written more concisely:
 304 .RS 4
 305 .TP 1.2i
 306 .BR S_ISREG (m)
 307 is it a regular file?
 308 .TP
 309 .BR S_ISDIR (m)
 310 directory?
 311 .TP
 312 .BR S_ISCHR (m)
 313 character device?
 314 .TP
 315 .BR S_ISBLK (m)
 316 block device?
 317 .TP
 318 .BR S_ISFIFO (m)
 319 FIFO (named pipe)?
 320 .TP
 321 .BR S_ISLNK (m)
 322 symbolic link?  (Not in POSIX.1-1996.)
 323 .TP
 324 .BR S_ISSOCK (m)
 325 socket?  (Not in POSIX.1-1996.)
 326 .RE
 327 .PP
 328 The preceding code snippet could thus be rewritten as:
 329
 330 .nf
 331 .in +4n
 332 stat(pathname, &sb);
 333 if (S_ISREG(sb.st_mode)) {
 334     /* Handle regular file */
 335 }
 336 .in
 337 .fi
 338 .PP
 339 The definitions of most of the above file type test macros
 340 are provided if any of the following feature test macros are defined:
 341 .BR _BSD_SOURCE
 342 (in glibc 2.19 and earlier),
 343 .BR _SVID_SOURCE
 344 (in glibc 2.19 and earlier),
 345 or
 346 .BR _DEFAULT_SOURCE
 347 (in glibc 2.20 and later).
 348 In addition, definitions of all of the above macros except
 349 .BR S_IFSOCK
 350 and
 351 .BR S_ISSOCK ()
 352 are provided if
 353 .BR _XOPEN_SOURCE
 354 is defined.
 355 The definition of
 356 .BR S_IFSOCK
 357 can also be exposed by defining
 358 .BR _XOPEN_SOURCE
 359 with a value of 500 or greater.
 360
 361 The definition of
 362 .BR S_ISSOCK ()
 363 is exposed if any of the following feature test macros is defined:
 364 .BR _BSD_SOURCE
 365 (in glibc 2.19 and earlier),
 366 .BR _DEFAULT_SOURCE
 367 (in glibc 2.20 and later),
 368 .BR _XOPEN_SOURCE
 369 with a value of 500 or greater, or
 370 .BR _POSIX_C_SOURCE
 371 with a value of 200112L or greater.
 372 .PP
 373 The following mask values are defined for
 374 the file permissions component of the
 375 .I st_mode
 376 field:
 377 .in +4n
 378 .TS
 379 lB l l.
 380 S_ISUID 0004000 set-user-ID bit
 381 S_ISGID 0002000 set-group-ID bit (see below)
 382 S_ISVTX 0001000 sticky bit (see below)
 383
 384 S_IRWXU   00700 mask for file owner permissions
 385 S_IRUSR   00400 owner has read permission
 386 S_IWUSR   00200 owner has write permission
 387 S_IXUSR   00100 owner has execute permission
 388
 389 S_IRWXG   00070 mask for group permissions
 390 S_IRGRP   00040 group has read permission
 391 S_IWGRP   00020 group has write permission
 392 S_IXGRP   00010 group has execute permission
 393
 394 S_IRWXO   00007 T{
 395 mask for permissions for others (not in group)
 396 T}
 397 S_IROTH   00004 others have read permission
 398 S_IWOTH   00002 others have write permission
 399 S_IXOTH   00001 others have execute permission
 400 .TE
 401 .in
 402 .P
 403 The set-group-ID bit
 404 .RB ( S_ISGID )
 405 has several special uses.
 406 For a directory, it indicates that BSD semantics is to be used
 407 for that directory: files created there inherit their group ID from
 408 the directory, not from the effective group ID of the creating process,
 409 and directories created there will also get the
 410 .B S_ISGID
 411 bit set.
 412 For a file that does not have the group execution bit
 413 .RB ( S_IXGRP )
 414 set,
 415 the set-group-ID bit indicates mandatory file/record locking.
 416 .P
 417 The sticky bit
 418 .RB ( S_ISVTX )
 419 on a directory means that a file
 420 in that directory can be renamed or deleted only by the owner
 421 of the file, by the owner of the directory, and by a privileged
 422 process.
 423 .\"
 424 .\"
 425 .SS fstatat()
 426 The
 427 .BR fstatat ()
 428 system call operates in exactly the same way as
 429 .BR stat (),
 430 except for the differences described here.
 431
 432 If the pathname given in
 433 .I pathname
 434 is relative, then it is interpreted relative to the directory
 435 referred to by the file descriptor
 436 .I dirfd
 437 (rather than relative to the current working directory of
 438 the calling process, as is done by
 439 .BR stat ()
 440 for a relative pathname).
 441
 442 If
 443 .I pathname
 444 is relative and
 445 .I dirfd
 446 is the special value
 447 .BR AT_FDCWD ,
 448 then
 449 .I pathname
 450 is interpreted relative to the current working
 451 directory of the calling process (like
 452 .BR stat ()).
 453
 454 If
 455 .I pathname
 456 is absolute, then
 457 .I dirfd
 458 is ignored.
 459
 460 .I flags
 461 can either be 0, or include one or more of the following flags ORed:
 462 .TP
 463 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
 464 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
 465 If
 466 .I pathname
 467 is an empty string, operate on the file referred to by
 468 .IR dirfd
 469 (which may have been obtained using the
 470 .BR open (2)
 471 .B O_PATH
 472 flag).
 473 If
 474 .I dirfd
 475 is
 476 .BR AT_FDCWD ,
 477 the call operates on the current working directory.
 478 In this case,
 479 .I dirfd
 480 can refer to any type of file, not just a directory.
 481 This flag is Linux-specific; define
 482 .B _GNU_SOURCE
 483 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
 484 to obtain its definition.
 485 .TP
 486 .BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)"
 487 Don't automount the terminal ("basename") component of
 488 .I pathname
 489 if it is a directory that is an automount point.
 490 This allows the caller to gather attributes of an automount point
 491 (rather than the location it would mount).
 492 This flag can be used in tools that scan directories
 493 to prevent mass-automounting of a directory of automount points.
 494 The
 495 .B AT_NO_AUTOMOUNT
 496 flag has no effect if the mount point has already been mounted over.
 497 This flag is Linux-specific; define
 498 .B _GNU_SOURCE
 499 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
 500 to obtain its definition.
 501 .TP
 502 .B AT_SYMLINK_NOFOLLOW
 503 If
 504 .I pathname
 505 is a symbolic link, do not dereference it:
 506 instead return information about the link itself, like
 507 .BR lstat ().
 508 (By default,
 509 .BR fstatat ()
 510 dereferences symbolic links, like
 511 .BR stat ().)
 512 .PP
 513 See
 514 .BR openat (2)
 515 for an explanation of the need for
 516 .BR fstatat ().
 517 .SH RETURN VALUE
 518 On success, zero is returned.
 519 On error, \-1 is returned, and
 520 .I errno
 521 is set appropriately.
 522 .SH ERRORS
 523 .TP
 524 .B EACCES
 525 Search permission is denied for one of the directories
 526 in the path prefix of
 527 .IR pathname .
 528 (See also
 529 .BR path_resolution (7).)
 530 .TP
 531 .B EBADF
 532 .I fd
 533 is bad.
 534 .TP
 535 .B EFAULT
 536 Bad address.
 537 .TP
 538 .B ELOOP
 539 Too many symbolic links encountered while traversing the path.
 540 .TP
 541 .B ENAMETOOLONG
 542 .I pathname
 543 is too long.
 544 .TP
 545 .B ENOENT
 546 A component of
 547 .I pathname
 548 does not exist, or
 549 .I pathname
 550 is an empty string.
 551 .TP
 552 .B ENOMEM
 553 Out of memory (i.e., kernel memory).
 554 .TP
 555 .B ENOTDIR
 556 A component of the path prefix of
 557 .I pathname
 558 is not a directory.
 559 .TP
 560 .B EOVERFLOW
 561 .I pathname
 562 or
 563 .I fd
 564 refers to a file whose size, inode number,
 565 or number of blocks cannot be represented in, respectively, the types
 566 .IR off_t ,
 567 .IR ino_t ,
 568 or
 569 .IR blkcnt_t .
 570 This error can occur when, for example,
 571 an application compiled on a 32-bit platform without
 572 .I -D_FILE_OFFSET_BITS=64
 573 calls
 574 .BR stat ()
 575 on a file whose size exceeds
 576 .I (1<<31)-1
 577 bytes.
 578 .PP
 579 The following additional errors can occur for
 580 .BR fstatat ():
 581 .TP
 582 .B EBADF
 583 .I dirfd
 584 is not a valid file descriptor.
 585 .TP
 586 .B EINVAL
 587 Invalid flag specified in
 588 .IR flags .
 589 .TP
 590 .B ENOTDIR
 591 .I pathname
 592 is relative and
 593 .I dirfd
 594 is a file descriptor referring to a file other than a directory.
 595 .SH VERSIONS
 596 .BR fstatat ()
 597 was added to Linux in kernel 2.6.16;
 598 library support was added to glibc in version 2.4.
 599 .SH CONFORMING TO
 600 .BR stat (),
 601 .BR fstat (),
 602 .BR lstat ():
 603 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008.
 604 .\" SVr4 documents additional
 605 .\" .BR fstat ()
 606 .\" error conditions EINTR, ENOLINK, and EOVERFLOW.  SVr4
 607 .\" documents additional
 608 .\" .BR stat ()
 609 .\" and
 610 .\" .BR lstat ()
 611 .\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
 612
 613 .BR fstatat ():
 614 POSIX.1-2008.
 615
 616 According to POSIX.1-2001,
 617 .BR lstat ()
 618 on a symbolic link need return valid information only in the
 619 .I st_size
 620 field and the file-type component of the
 621 .IR st_mode
 622 field of the
 623 .IR stat
 624 structure.
 625 POSIX.1-2008 tightens the specification, requiring
 626 .BR lstat ()
 627 to return valid information in all fields except the permission bits in
 628 .IR st_mode .
 629
 630 Use of the
 631 .I st_blocks
 632 and
 633 .I st_blksize
 634 fields may be less portable.
 635 (They were introduced in BSD.
 636 The interpretation differs between systems,
 637 and possibly on a single system when NFS mounts are involved.)
 638 If you need to obtain the definition of the
 639 .IR blkcnt_t
 640 or
 641 .IR blksize_t
 642 types from
 643 .IR <sys/stat.h> ,
 644 then define
 645 .BR _XOPEN_SOURCE
 646 with the value 500 or greater (before including
 647 .I any
 648 header files).
 649 .LP
 650 POSIX.1-1990 did not describe the
 651 .BR S_IFMT ,
 652 .BR S_IFSOCK ,
 653 .BR S_IFLNK ,
 654 .BR S_IFREG ,
 655 .BR S_IFBLK ,
 656 .BR S_IFDIR ,
 657 .BR S_IFCHR ,
 658 .BR S_IFIFO ,
 659 .B S_ISVTX
 660 constants, but instead demanded the use of
 661 the macros
 662 .BR S_ISDIR (),
 663 and so on.
 664 The
 665 .BR S_IF*
 666 constants are present in POSIX.1-2001 and later.
 667
 668 The
 669 .BR S_ISLNK ()
 670 and
 671 .BR S_ISSOCK ()
 672 macros are not in
 673 POSIX.1-1996, but both are present in POSIX.1-2001;
 674 the former is from SVID 4, the latter from SUSv2.
 675 .LP
 676 UNIX\ V7 (and later systems) had
 677 .BR S_IREAD ,
 678 .BR S_IWRITE ,
 679 .BR S_IEXEC ,
 680 where POSIX
 681 prescribes the synonyms
 682 .BR S_IRUSR ,
 683 .BR S_IWUSR ,
 684 .BR S_IXUSR .
 685 .SS Other systems
 686 Values that have been (or are) in use on various systems:
 687 .ad l
 688 .TS
 689 l l l l l.
 690 hex     name    ls      octal   description
 691 f000    S_IFMT          170000  mask for file type
 692 0000                    000000  T{
 693 SCO out-of-service inode; BSD unknown type; SVID-v2 and XPG2
 694 have both 0 and 0100000 for ordinary file
 695 T}
 696 1000    S_IFIFO p|      010000  FIFO (named pipe)
 697 2000    S_IFCHR c       020000  character special (V7)
 698 3000    S_IFMPC         030000  multiplexed character special (V7)
 699 4000    S_IFDIR d/      040000  directory (V7)
 700 5000    S_IFNAM         050000  T{
 701 XENIX named special file with two subtypes, distinguished by
 702 \fIst_rdev\fP values 1, 2
 703 T}
 704 0001    S_INSEM s       000001  XENIX semaphore subtype of IFNAM
 705 0002    S_INSHD m       000002  XENIX shared data subtype of IFNAM
 706 6000    S_IFBLK b       060000  block special (V7)
 707 7000    S_IFMPB         070000  multiplexed block special (V7)
 708 8000    S_IFREG -       100000  regular (V7)
 709 9000    S_IFCMP         110000  VxFS compressed
 710 9000    S_IFNWK n       110000  network special (HP-UX)
 711 a000    S_IFLNK l@      120000  symbolic link (BSD)
 712 b000    S_IFSHAD                130000  T{
 713 Solaris shadow inode for ACL (not seen by user space)
 714 T}
 715 c000    S_IFSOCK        s=      140000  socket (BSD; also "S_IFSOC" on VxFS)
 716 d000    S_IFDOOR        D>      150000  Solaris door
 717 e000    S_IFWHT w%      160000  BSD whiteout (not used for inode)
 718 0200    S_ISVTX         001000  T{
 719 sticky bit: save swapped text even after use (V7)
 720 .br
 721 reserved (SVID-v2)
 722 .br
 723 On nondirectories: don't cache this file (SunOS)
 724 .br
 725 On directories: restricted deletion flag (SVID-v4.2)
 726 T}
 727 0400    S_ISGID         002000  T{
 728 set-group-ID on execution (V7)
 729 .br
 730 for directories: use BSD semantics for propagation of GID
 731 T}
 732 0400    S_ENFMT         002000  T{
 733 System V file locking enforcement (shared with S_ISGID)
 734 T}
 735 0800    S_ISUID         004000  set-user-ID on execution (V7)
 736 0800    S_CDF           004000  T{
 737 directory is a context dependent file (HP-UX)
 738 T}
 739 .TE
 740 .ad
 741
 742 A sticky command appeared in Version 32V AT&T UNIX.
 743 .SH NOTES
 744 On Linux,
 745 .BR lstat ()
 746 will generally not trigger automounter action, whereas
 747 .BR stat ()
 748 will (but see
 749 .BR fstatat (2)).
 750
 751 For most files under the
 752 .I /proc
 753 directory,
 754 .BR stat ()
 755 does not return the file size in the
 756 .I st_size
 757 field; instead the field is returned with the value 0.
 758 .SS Timestamp fields
 759 Older kernels and older standards did not support nanosecond timestamp
 760 fields.
 761 Instead, there were three timestamp
 762 .RI fields\(em st_atime ,
 763 .IR st_mtime ,
 764 and
 765 .IR st_ctime \(emtyped
 766 as
 767 .IR time_t
 768 that recorded timestamps with one-second precision.
 769
 770 Since kernel 2.5.48, the
 771 .I stat
 772 structure supports nanosecond resolution for the three file timestamp fields.
 773 The nanosecond components of each timestamp are available
 774 via names of the form
 775 .IR st_atim.tv_nsec
 776 if the
 777 .B _BSD_SOURCE
 778 or
 779 .B _SVID_SOURCE
 780 feature test macro is defined.
 781 Nanosecond timestamps are nowadays standardized,
 782 starting with POSIX.1-2008, and, starting with version 2.12,
 783 glibc also exposes the nanosecond component names if
 784 .BR _POSIX_C_SOURCE
 785 is defined with the value 200809L or greater, or
 786 .BR _XOPEN_SOURCE
 787 is defined with the value 700 or greater.
 788 If none of the aforementioned macros are defined,
 789 then the nanosecond values are exposed with names of the form
 790 .IR st_atimensec .
 791
 792 Nanosecond timestamps are supported on XFS, JFS, Btrfs, and
 793 ext4 (since Linux 2.6.23).
 794 .\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80
 795 Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs.
 796 On filesystems that do not support subsecond timestamps,
 797 the nanosecond fields are returned with the value 0.
 798 .SS Underlying kernel interface
 799 Over time, increases in the size of the
 800 .I stat
 801 structure have led to three successive versions of
 802 .BR stat ():
 803 .IR sys_stat ()
 804 (slot
 805 .IR __NR_oldstat ),
 806 .IR sys_newstat ()
 807 (slot
 808 .IR __NR_stat ),
 809 and
 810 .I sys_stat64()
 811 (new in kernel 2.4; slot
 812 .IR __NR_stat64 ).
 813 The glibc
 814 .BR stat ()
 815 wrapper function hides these details from applications,
 816 invoking the most recent version of the system call provided by the kernel,
 817 and repacking the returned information if required for old binaries.
 818 Similar remarks apply for
 819 .BR fstat ()
 820 and
 821 .BR lstat ().
 822 .\"
 823 .\" A note from Andries Brouwer, July 2007
 824 .\"
 825 .\" > Is the story not rather more complicated for some calls like
 826 .\" > stat(2)?
 827 .\"
 828 .\" Yes and no, mostly no. See /usr/include/sys/stat.h .
 829 .\"
 830 .\" The idea is here not so much that syscalls change, but that
 831 .\" the definitions of struct stat and of the types dev_t and mode_t change.
 832 .\" This means that libc (even if it does not call the kernel
 833 .\" but only calls some internal function) must know what the
 834 .\" format of dev_t or of struct stat is.
 835 .\" The communication between the application and libc goes via
 836 .\" the include file <sys/stat.h> that defines a _STAT_VER and
 837 .\" _MKNOD_VER describing the layout of the data that user space
 838 .\" uses. Each (almost each) occurrence of stat() is replaced by
 839 .\" an occurrence of xstat() where the first parameter of xstat()
 840 .\" is this version number _STAT_VER.
 841 .\"
 842 .\" Now, also the definitions used by the kernel change.
 843 .\" But glibc copes with this in the standard way, and the
 844 .\" struct stat as returned by the kernel is repacked into
 845 .\" the struct stat as expected by the application.
 846 .\" Thus, _STAT_VER and this setup cater for the application-libc
 847 .\" interface, rather than the libc-kernel interface.
 848 .\"
 849 .\" (Note that the details depend on gcc being used as c compiler.)
 850
 851 The underlying system call employed by the glibc
 852 .BR fstatat ()
 853 wrapper function is actually called
 854 .BR fstatat64 ().
 855 .SH EXAMPLE
 856 The following program calls
 857 .BR stat ()
 858 and displays selected fields in the returned
 859 .I stat
 860 structure.
 861 .nf
 862
 863 #include <sys/types.h>
 864 #include <sys/stat.h>
 865 #include <time.h>
 866 #include <stdio.h>
 867 #include <stdlib.h>
 868
 869 int
 870 main(int argc, char *argv[])
 871 {
 872     struct stat sb;
 873
 874     if (argc != 2) {
 875         fprintf(stderr, "Usage: %s <pathname>\\n", argv[0]);
 876         exit(EXIT_FAILURE);
 877     }
 878
 879     if (stat(argv[1], &sb) == \-1) {
 880         perror("stat");
 881         exit(EXIT_FAILURE);
 882     }
 883
 884     printf("File type:                ");
 885
 886     switch (sb.st_mode & S_IFMT) {
 887     case S_IFBLK:  printf("block device\\n");            break;
 888     case S_IFCHR:  printf("character device\\n");        break;
 889     case S_IFDIR:  printf("directory\\n");               break;
 890     case S_IFIFO:  printf("FIFO/pipe\\n");               break;
 891     case S_IFLNK:  printf("symlink\\n");                 break;
 892     case S_IFREG:  printf("regular file\\n");            break;
 893     case S_IFSOCK: printf("socket\\n");                  break;
 894     default:       printf("unknown?\\n");                break;
 895     }
 896
 897     printf("I\-node number:            %ld\\n", (long) sb.st_ino);
 898
 899     printf("Mode:                     %lo (octal)\\n",
 900             (unsigned long) sb.st_mode);
 901
 902     printf("Link count:               %ld\\n", (long) sb.st_nlink);
 903     printf("Ownership:                UID=%ld   GID=%ld\\n",
 904             (long) sb.st_uid, (long) sb.st_gid);
 905
 906     printf("Preferred I/O block size: %ld bytes\\n",
 907             (long) sb.st_blksize);
 908     printf("File size:                %lld bytes\\n",
 909             (long long) sb.st_size);
 910     printf("Blocks allocated:         %lld\\n",
 911             (long long) sb.st_blocks);
 912
 913     printf("Last status change:       %s", ctime(&sb.st_ctime));
 914     printf("Last file access:         %s", ctime(&sb.st_atime));
 915     printf("Last file modification:   %s", ctime(&sb.st_mtime));
 916
 917     exit(EXIT_SUCCESS);
 918 }
 919 .fi
 920 .SH SEE ALSO
 921 .BR ls (1),
 922 .BR stat (1),
 923 .BR access (2),
 924 .BR chmod (2),
 925 .BR chown (2),
 926 .BR readlink (2),
 927 .BR utime (2),
 928 .BR capabilities (7),
 929 .BR symlink (7)
 930 .SH COLOPHON
 931 This page is part of release 3.68 of the Linux
 932 .I man-pages
 933 project.
 934 A description of the project,
 935 information about reporting bugs,
 936 and the latest version of this page,
 937 can be found at
 938 \%http://www.kernel.org/doc/man\-pages/.