World Library  
Flag as Inappropriate
Email this Article

Stat (system call)

Article Id: WHEBN0000920765
Reproduction Date:

Title: Stat (system call)  
Author: World Heritage Encyclopedia
Language: English
Subject: Atime, STAT, POSIX, C POSIX library, User space
Collection: C Posix Library, Posix, System Calls, Unix File System-Related Software
Publisher: World Heritage Encyclopedia

Stat (system call)

stat() is a Unix system call that returns file attributes about an inode. The semantics of stat() vary between operating systems. As an example, the Unix command ls uses it to retrieve information on (among many others):

  • atime: time of last access (ls -lu),
  • mtime: time of last modification (ls -l), and
  • ctime: time of last status change (ls -lc).

stat appeared in Version 1 Unix. It is among the few original Unix system calls to change, with Version 4's addition of group permissions and larger file size.[1]


  • stat() functions 1
  • stat structure 2
  • Criticism of atime 3
    • Solutions 3.1
  • ctime 4
  • Time granularity 5
  • Example 6
  • References 7
  • External links 8

stat() functions

The C POSIX library header sys/stat.h, found on POSIX and other Unix-like operating systems, declares the stat() functions, as well as related function called fstat() and lstat(). The functions take a struct stat buffer argument, which is used to return the file attributes. On success, the functions return zero, and on error, −1 is returned and errno is set appropriately.

The stat() and lstat() functions take a filename argument. If the file name is a symbolic link, stat() returns attributes of the eventual target of the link, while lstat() returns attributes of the link itself. The fstat() function takes a file descriptor argument instead, and returns attributes of the file that it identifies.

The family of functions was extended to implement large file support. Functions named stat64(), lstat64() and fstat64() return attributes in a struct stat64 structure, which represents file sizes with a 64-bit type, allowing the functions to work on files 2 GiB and larger. When the _FILE_OFFSET_BITS macro is defined to 64, these 64-bit functions are available under the original names.

The functions are defined as:

int stat(const char *filename, struct stat *buf);
int lstat(const char *filename, struct stat *buf);
int fstat(int filedesc, struct stat *buf);

stat structure

This structure is defined in sys/stat.h header file as follows, although implementations are free to define additional fields:[2]

struct stat {
        mode_t                  st_mode;
        ino_t                   st_ino;
        dev_t                   st_dev;
        dev_t                   st_rdev;
        nlink_t                 st_nlink;
        uid_t                   st_uid;
        gid_t                   st_gid;
        off_t                   st_size;
        struct timespec         st_atim;
        struct timespec         st_mtim;
        struct timespec         st_ctim;
        blksize_t               st_blksize;
        blkcnt_t                st_blocks;

POSIX.1 does not require st_rdev, st_blocks and st_blksize members; these fields are defined as part of XSI option in the Single Unix Specification.

In older versions of POSIX.1 standard, the time-related fields were defined as st_atime, st_mtime and st_ctime, and were of type time_t. Since the 2008 version of the standard, these fields were renamed to st_atim, st_mtim and st_ctim, respectively, of type struct timespec, since this structure provides a higher resolution time unit. For the sake of compatibility, implementations can define the old names in terms of the tv_sec member of struct timespec. For example, st_atime can be defined as st_atim.tv_sec.[2]

The struct stat structure, also defined in sys/stat.h, includes at least the following members:

  • st_dev – identifier of device containing file
  • st_ino – inode number
  • st_mode – protection mode; see also Unix permissions
  • st_nlink – reference count of hard links
  • st_uid – user identifier of owner
  • st_gid – group identifier of owner
  • st_rdev – device identifier (if special file)
  • st_size – total file size, in bytes
  • st_atime – time of last access
  • st_mtime – time of last modification
  • st_ctime – time of last status change
  • st_blksize – preferred block size for file system I/O, which can depend upon both the system and the type of file system[3]
  • st_blocks – number of blocks allocated in multiples of DEV_BSIZE (usually 512 bytes).

The st_mode field is a bit field. It combines the file access modes and also indicates any special file type. There are many macros to work with the different mode flags and file types.

Criticism of atime

Reading a file changes its atime eventually requiring a disk write, which has been criticized as it is inconsistent with a read only file system.

This behaviour can usually be disabled by adding the noatime mount option in /etc/fstab. Turning off atime updating breaks POSIX compliance, and some applications, such as mbox-driven "new mail" notifications,[4] and some file usage watching utilities, notably tmpwatch.

Linux kernel developer Ingo Molnár called atime "perhaps the most stupid Unix design idea of all times,"[5][6] adding: "[T]hink about this a bit: 'For every file that is read from the disk, let's do a ... write to the disk! And, for every file that is already cached and which we read from the cache ... do a write to the disk!'" He further emphasized the performance impact thus:

atime updates are by far the biggest I/O performance deficiency that Linux has today. Getting rid of atime updates would give us more everyday Linux performance than all the pagecache speedups of the past 10 years, _combined_.

File system cache may significantly reduce this activity to one disk write per cache flush.


Current versions of Linux, Mac OS X, Solaris, FreeBSD, NetBSD, and OpenBSD support a noatime mount option, which causes the atime field never to be updated. This breaks compliance with POSIX.

Current versions of the Linux kernel support four mount options, which can be specified in fstab:

  • strictatime (formerly atime, and formerly the default; strictatime as of 2.6.30) – always update atime
  • relatime ("relative atime", introduced in 2.6.20 and the default as of 2.6.30) – only update atime under certain circumstances (explained below)
  • nodiratime – never update atime of directories, but do update atime of other files
  • noatime – never update atime of any file or directory; implies nodiratime; highest performance, but least compatible

strictatime accords with POSIX. File systems mounted with the noatime option do not update the atime on reads, while the relatime option provides for updates only if the previous atime is older than the mtime or ctime, or the previous atime is over 24 hours in the past. Many users use noatime without problem, so long as they do not use an application which depends on atime, and this offers some benefits over relatime (no writing of atime ever on read).

Alan Cox described the alternatives in the following way:

"Turn off atime and it is very non standards compliant, turn to relatime and it is not standards compliant but nobody will break (which is good)"

As of version 2.6.30, which was released on June 9, 2009, Linux kernel defaults to relatime,[7] resulting in not updating atime values on all file reads. The behavior behind the relatime mount option offers sufficient performance for most purposes and should not break any significant applications, as it has been extensively discussed.[8] Initially, relatime only updated atime if atime < mtime or atime < ctime; that was subsequently modified to update atimes that were 24 hours old or older, so that tmpwatch and Debian's popularity counter (popcon) would behave properly.[9]

Behavior introduced by the Linux kernel's relatime option, although offering performance improvements, breaks the compliance with POSIX specifications and causes issues with certain programs depending on precise atime updates. As an alternative, lazyupdate was merged into the Linux kernel mainline in kernel version 4.0, which was released on April 12, 2015. Introducing new mount option lazytime, it allows POSIX-style atime updates to be performed in-memory and flushed to disk together with some non-time-related I/O operations on the same file; atime updates are also flushed to disk when some of the sync system calls is executed, or before the file's in-memory inode is evicted from the filesystem cache. Additionally, it is possible to configure for how long atime modifications can remain unflushed. That way, lazytime retains POSIX compatibility while offering performance improvements.[10][11]


ctime originally meant creation time,[12] however it has since been used almost always to refer to change time. It is updated any time file content changes (together with mtime), and also by changes in metadata such as file permissions, file ownership, and creation and deletion of hard links. In some implementations, ctime is affected by renaming a file (both original Unix and modern Linux tend to do this).

Unlike atime and mtime, ctime cannot be set to an arbitrary value with utime(), as used by the touch utility, for example. Instead, when utime() is used, the ctime value is set to the current time.

Time granularity

  • time_t provides times accurate to one second.
  • Some filesystems provide finer granularity. Solaris 2.1 introduced a microsecond resolution with UFS in 1992 and a nanosecond resolution with ZFS.
  • In Linux kernels 2.5.48 and above, the stat structure supports nanosecond resolution for the three file timestamp fields. These are exposed as additional fields in the stat structure.[13][14]
  • The resolution of create time on FAT filesystem is 10 milliseconds, while resolution of its write time is two seconds, and access time has a resolution of one day thus it acts as the access date.[15]




main(int argc, char *argv[])

        struct stat sb;
        struct passwd *pwuser;
        struct group *grpnam;

        if (argc < 2)
                fprintf(stderr, "Usage: %s: file ...\n", argv[0]);

        for (int i = 1; i < argc; i++)
                if (-1 == stat(argv[i], &sb))

                if (NULL == (pwuser = getpwuid(sb.st_uid)))

                if (NULL == (grpnam = getgrgid(sb.st_gid)))

                printf("%s:\n", argv[i]);
                printf("\tinode: %u\n", sb.st_ino);
                printf("\towner: %u (%s)\n", sb.st_uid, pwuser->pw_name);
                printf("\tgroup: %u (%s)\n", sb.st_gid, grpnam->gr_name);
                printf("\tperms: %o\n", sb.st_mode & (S_IRWXU | S_IRWXG | S_IRWXO));
                printf("\tlinks: %d\n", sb.st_nlink);
                printf("\tsize: %ld\n", sb.st_size);
                printf("\tatime: %s", ctime(&sb.st_atim.tv_sec));
                printf("\tmtime: %s", ctime(&sb.st_mtim.tv_sec));
                printf("\tctime: %s", ctime(&sb.st_ctim.tv_sec));


        return 0;


  1. ^  
  2. ^ a b Stevens & Rago 2013, p. 94.
  3. ^ "". The Open Group Base Specifications Issue 6—IEEE Std 1003.1, 2004 Edition. The Open Group. 2004. 
  4. ^ "the shell's $MAIL monitor ... depends on atime, pronouncing new email with atime($MAIL) < mtime($MAIL)"
  5. ^ Kernel Trap: Linux: Replacing atime With relatime, by Jeremy, August 7, 2007
  6. ^ Once upon atime, LWN, by Jonathan Corbet, August 8, 2007
  7. ^ Linux kernel 2.6.30, Linux Kernel Newbies
  8. ^ That massive filesystem thread, LWN, by Jonathan Corbet, March 31, 2009
  9. ^ Relatime Recap, Valerie Aurora
  10. ^ "Linux kernel 4.0, Section 1.5. 'lazytime' option for better update of file timestamps". May 1, 2015. Retrieved May 2, 2015. 
  11. ^ Jonathan Corbet (November 19, 2014). "Introducing lazytime".  
  12. ^
  13. ^ "stat(2) - Linux manual page". Retrieved February 27, 2015. 
  14. ^ Andreas Jaeger (December 2, 2002), struct stat.h with nanosecond resolution, mail archive of the mailing list for the glibc project. 
  15. ^ MSDN: File Times
  • IEEE Std 1003.1, 2004, documentation for fstat(2). Retrieved 2012-06-07.
  • stat(2) Linux man page. Retrieved 2012-06-07.
  • W. Richard, Stevens; Stephen A., Rago (May 24, 2013). Advanced Programming in the UNIX Environment (Third ed.).  

External links

  • An example showing how to use stat()
  • stat() in Perl
  • stat() in PHP
  • atime and relatime
This article was sourced from Creative Commons Attribution-ShareAlike License; additional terms may apply. World Heritage Encyclopedia content is assembled from numerous content providers, Open Access Publishing, and in compliance with The Fair Access to Science and Technology Research Act (FASTR), Wikimedia Foundation, Inc., Public Library of Science, The Encyclopedia of Life, Open Book Publishers (OBP), PubMed, U.S. National Library of Medicine, National Center for Biotechnology Information, U.S. National Library of Medicine, National Institutes of Health (NIH), U.S. Department of Health & Human Services, and, which sources content from all federal, state, local, tribal, and territorial government publication portals (.gov, .mil, .edu). Funding for and content contributors is made possible from the U.S. Congress, E-Government Act of 2002.
Crowd sourced content that is contributed to World Heritage Encyclopedia is peer reviewed and edited by our editorial staff to ensure quality scholarly research articles.
By using this site, you agree to the Terms of Use and Privacy Policy. World Heritage Encyclopedia™ is a registered trademark of the World Public Library Association, a non-profit organization.

Copyright © World Library Foundation. All rights reserved. eBooks from Project Gutenberg are sponsored by the World Library Foundation,
a 501c(4) Member's Support Non-Profit Organization, and is NOT affiliated with any governmental agency or department.