stat (system call)
||The examples and perspective in this article may not represent a worldwide view of the subject. (February 2015)|
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).
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);
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
- st_blocks – 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:
- 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 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).
Unlike atime and mtime, 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.
- McIlroy, M. D. (1987). A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986 (Technical report). CSTR. Bell Labs. 139.
- "<sys/stat.h>". The Open Group Base Specifications Issue 6—IEEE Std 1003.1, 2004 Edition. The Open Group. 2004.
- http://email@example.com/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
- "stat(2) - Linux manual page". man7.org. Retrieved February 27, 2015.
- Andreas Jaeger (December 2, 2002), struct stat.h with nanosecond resolution, mail archive of the firstname.lastname@example.org mailing list for the glibc project.
- MSDN: File Times