Contents

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 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_BITSmacro is defined to 64, these 64-bit functions are available under the original names.

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:

This section may lend undue weight to certain ideas, incidents, or controversies. Please help to create a more balanced presentation. Discuss and resolve this issue before removing this message. (March 2015)

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. File system cache may significantly reduce this activity to one disk write per cache flush.

Linux kernel developer Ingo Molnár publicly criticized the concept and performance impact of atime in 2007,[4][5] and in 2009, the relatime mount option had become the default, which addresses this criticism.[6] 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.[7] 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.[8]

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, which conforms to the behavior defined by POSIX

relatime ("relative atime", introduced in 2.6.20 and the default as of 2.6.30) – only update atime under certain circumstances: if the previous atime is older than the mtime or ctime, or the previous atime is over 24 hours in the past

nodiratime – never update atime of directories, but do update atime of other files

Current versions of Linux, Mac OS X, Solaris, FreeBSD, and NetBSD support a noatime mount option in /etc/fstab, which causes the atime field never to be updated. Turning off atime updating breaks POSIX compliance, and some applications, such as mbox-driven "new mail" notifications,[9] and some file usage watching utilities, notably tmpwatch.

Version 4.0 of the Linux kernel mainline, which was released on April 12, 2015, introduced the 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 inode change time. It is updated any time file metadata stored in the inode changes, 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.