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() 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

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

Block size for filesystem I/O

st_blocks

Number of blocks allocated

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

Writing to a file changes its mtime and ctime, while reading a file changes its atime. As a result, on a POSIX-compliant system, reading a file causes a write, which has been criticized. This behaviour can usually be disabled by adding a mount option in /etc/fstab.

However, turning off atime updating breaks POSIX compliance, and some applications, notably the Mutt mail reader (in some configurations), 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_.

Solutions

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 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 references.

ctime

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.

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.

The FAT filesystem provides timestamps with a granularity of two seconds.

References

• IEEE Std 1003.1, 2004, documentation for fstat(2). Retrieved 2012-06-07.
• stat(2) Linux man page. Retrieved 2012-06-07.

External links

• An example showing how to use stat()
• stat() in Perl
• stat() in PHP
• atime and relatime