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 command uses this system call to retrieve timestamps:
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.
The C POSIX library header , found on POSIX and other Unix-like operating systems, declares <code>stat()</code> and related functions.
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.
The metadata structure is defined in the header. The following shows the base fields, but an implementation is free to include additional fields:
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:
The following C program reports metadata about each file passed via the command-line using to query the system for the information.