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 (
- mtime: time of last modification (
ls -l), and
- ctime: time of last status change (
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
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);
The struct stat structure, also defined in <sys/stat.h>, includes at least the following members:
- Identifier of device containing file
- Inode number
- Protection mode. See also Unix permissions.
- Reference count of hard links
- User identifier of owner
- Group identifier of owner
- Device identifier (if special file)
- Total file size, in bytes
- Time of last access
- Time of last modification
- Time of last status change
- Block size for filesystem I/O
- Number of blocks allocated
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, 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," 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 support four mount options, which can be specified in fstab:
atime, and formerly the default;
strictatimeas 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 2.6.30 (9 June 2009), Linux defaults to
relatime, so that it will not update atime on all file reads. The behavior offers sufficient performance for most purposes and should not break any significant applications. Extended discussion of filesystem performance preceded the decision. Indeed,
relatime by default was the first patch Linus applied following the 2.6.29 release. In initial patches
relatime only updated atime if atime < mtime or atime < ctime; this 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.
See further discussion at the reference.
ctime originally meant creation time, 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).
ctime cannot be set to an arbitrary value with
utime() (as used e.g. by
touch). Instead, when utime() is used, the
ctime value is set to the current time.
Granularity of mtime, etc.
time_t provides times accurate to one second.
Some filesystems provide finer granularity. 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.
- http://firstname.lastname@example.org/msg24912.html "the shell's $MAIL monitor ... depends on atime, pronouncing new email with atime($MAIL) < mtime($MAIL)"
- Kernel Trap: Linux: Replacing atime With relatime, by Jeremy, August 7, 2007
- Once upon atime, LWN, by Jonathan Corbet, August 8, 2007
- Linux 2 6 30, Linux Kernel Newbies
- That massive filesystem thread, LWN, by Jonathan Corbet, March 31, 2009
- Relatime Recap, Valerie Aurora