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