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