Stat (system call)

thumb|<code>stat</code> command line

is a Unix system call that queries the file system for metadata about a file (including special files such as directories). The metadata contains many fields including type, size, ownership, permissions and timestamps.

For example, the ls| command uses this system call to retrieve timestamps:

mtime: when last modified ()
atime: when last accessed ()
ctime: when last status changed ()

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.

Since at least 2004, the same-named shell command <code>stat</code> has been available for Linux to expose features of the system call via a command-line interface.

Functions

The C POSIX library header , found on POSIX and other Unix-like operating systems, declares <code>stat()</code> and related functions.

int stat(const char* path, struct stat* buf);

int lstat(const char* path, struct stat* buf);

int fstat(int filedesc, struct stat* buf);

</syntaxhighlight>

Each function accepts a pointer to a <code>struct stat</code> buffer which the function loads with information about the specified file. As typical for system calls, each function returns 0 on success, or on failure, sets errno to indicate the failure condition and returns −1.

The <code>stat()</code> and <code>lstat()</code> functions accept a path argument that specifies a file. If the path identifies a symbolic link, <code>stat()</code> returns attributes of the link target, whereas <code>lstat()</code> returns attributes of the link itself. The <code>fstat()</code> function accepts a file descriptor argument instead of a path, and returns attributes of the file that it identifies.

The library has been extended to support large files. Functions <code>stat64()</code>, <code>lstat64()</code> and <code>fstat64()</code> load information into a <code>struct stat64</code> buffer, which supports 64-bit sizes, allowing them to work with files 2 GiB and larger (up to 8 EiB). When the <code>_FILE_OFFSET_BITS</code> macro is defined as 64, the 64-bit functions are available as the original names.

Data structure

The metadata structure is defined in the header. The following shows the base fields, but an implementation is free to include additional fields:

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;

};

</syntaxhighlight>

POSIX.1 does not require <code>st_rdev</code>, <code>st_blocks</code> and <code>st_blksize</code> 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 <code>st_atime</code>, <code>st_mtime</code> and <code>st_ctime</code>, and were of type <code>time_t</code>. Since the 2008 version of the standard, these fields were renamed to <code>st_atim</code>, <code>st_mtim</code> and <code>st_ctim</code>, respectively, of type struct <code>timespec</code>, since this structure provides a higher resolution time unit. For the sake of compatibility, implementations can define the old names in terms of the <code>tv_sec</code> member of <code>struct timespec</code>. For example, <code>st_atime</code> can be defined as <code>st_atim.tv_sec</code>.

Fields include:

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

<!--

[Editor: The following might be useful information, but it way off topic for stat().]

Criticism of atime

Reading a file changes its 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, and in 2009, the mount option had become the default, which addresses this criticism. The behavior behind the mount option offers sufficient performance for most purposes and should not break any significant applications, as it has been extensively discussed. Initially, 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 and Debian's popularity counter (popcon) would behave properly.

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

(formerly , and formerly the default; as of 2.6.30) always update atime, which conforms to the behavior defined by POSIX
("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
never update atime of directories, but do update atime of other files
never update atime of any file or directory; implies ; highest performance, but least compatible
update atime according to specific circumstances laid out below

Current versions of Linux, macOS, Solaris, FreeBSD, and NetBSD support a 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, and some file usage watching utilities, notably tmpwatch.

The option on OpenBSD behaves more like Linux .

Version 4.0 of the Linux kernel mainline, which was released on April 12, 2015, introduced the new mount option . 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 are 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.

ctime

It is tempting to believe that originally meant creation time; however, while early Unix did have modification and creation times, the latter was changed to be access time before there was any C structure in which to call anything . The file systems retained just the access time () and modification time () through 6th edition Unix. The timestamp was added in the file system restructuring that occurred with Version 7 Unix, and has always referred 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. POSIX also mandates (last status change) update with nonzero write (system call)| (file modification). In some implementations, is affected by renaming a file, despite filenames not being stored in inodes: Both original Unix, which implemented a renaming by making a link (updating ) and then unlinking the old name (updating again) and modern Linux tend to do this.

Unlike and , cannot be set to an arbitrary value with , as used by the utility, for example. Instead, when is used, or for any other change to the inode other than an update to caused by

accessing the file, the value is set to the current time.

Time granularity

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

-->

Example

The following C program reports metadata about each file passed via the command-line using to query the system for the information.

include <stdio.h>
include <stdlib.h>
include <time.h>
include <sys/stat.h>
include <sys/types.h>

int main(int argc, char* argv[]) {

struct stat sb;

for (int i = 1; i < argc; i++) {

if (stat(argv[i], &sb) == -1) {

perror("stat failed");

exit(EXIT_FAILURE);

}

printf("%s:\n", argv[i]);

printf("\tinode: %u\n", sb.st_ino);

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

printf("\n");

}

return 0;

}

</syntaxhighlight>

References

External links

atime and relatime
IEEE Std 1003.1, 2004, documentation for fstat(2). Retrieved 2012-06-07.
stat() in Perl
stat() in PHP
stat(2) Linux man page. Retrieved 2012-06-07.