stat command linestat() is aUnixsystem call that queries thefile system formetadata about afile (includingspecial files such asdirectories). The metadata contains many fields includingtype,size, ownership,permissions andtimestamps.
For example, thels command uses this system call to retrieve timestamps:
ls -l)ls -lu)ls -lc)stat() appeared inVersion 1 Unix. It is among the few original Unixsystem calls to change, withVersion 4's addition ofgroup permissions and largerfile size.[1]
Since at least 2004, the same-namedshellcommandstat has been available forLinux to expose features of the system call via acommand-line interface.[2]
TheC POSIX library headersys/stat.h, found onPOSIX and otherUnix-likeoperating systems, declaresstat() and related functions.
intstat(constchar*path,structstat*buf);intlstat(constchar*path,structstat*buf);intfstat(intfiledesc,structstat*buf);
Each function accepts a pointer to astruct stat 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, setserrno to indicate the failure condition and returns −1.
Thestat() andlstat() functions accept apath argument that specifies a file. If the path identifies asymbolic link,stat() returns attributes of the link target, whereaslstat() returns attributes of the link itself. Thefstat() function accepts afile descriptor argument instead of a path, and returns attributes of the file that it identifies.
The library has been extended to supportlarge files. Functionsstat64(),lstat64() andfstat64() load information into astruct stat64 buffer, which supports 64-bit sizes, allowing them to work with files 2 GiB and larger (up to 8 EiB). When the_FILE_OFFSET_BITSmacro is defined as 64, the 64-bit functions are available as the original names.
The metadata structure is defined in thesys/stat.h header. The following shows the base fields, but an implementation is free to include additional fields:[3]
structstat{mode_tst_mode;ino_tst_ino;dev_tst_dev;dev_tst_rdev;nlink_tst_nlink;uid_tst_uid;gid_tst_gid;off_tst_size;structtimespecst_atim;structtimespecst_mtim;structtimespecst_ctim;blksize_tst_blksize;blkcnt_tst_blocks;};
POSIX.1 does not requirest_rdev,st_blocks andst_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 asst_atime,st_mtime andst_ctime, and were of typetime_t. Since the 2008 version of the standard, these fields were renamed tost_atim,st_mtim andst_ctim, respectively, of type structtimespec, since this structure provides a higher resolution time unit. For the sake of compatibility, implementations can define the old names in terms of thetv_sec member ofstruct timespec. For example,st_atime can be defined asst_atim.tv_sec.[3]
Fields include:
st_dev – identifier ofdevice containing filest_ino – inode numberst_mode – abit field containing file accessmodes andspecial file type; seeUnix permissionsst_nlink – reference count ofhard linksst_uid – user identifier of ownerst_gid – group identifier of ownerst_rdev – device identifier (ifspecial file)st_size – totalfile size, in bytesst_atime – time of last accessst_mtime – time of last modificationst_ctime – time of last status changest_blksize – preferredblock size for file system I/O, which can depend upon both the system and the type of file system[4]st_blocks – number of blocks allocated in multiples ofDEV_BSIZE (usually 512 bytes). | This sectionmay beconfusing or unclear to readers. Please helpclarify the section. There might be a discussion about this onthe talk page.(January 2023) (Learn how and when to remove this message) |
The followingC program reports metadata about each file passed via the command-line – usingstat() to query the system for the information.
#include<stdio.h>#include<stdlib.h>#include<time.h>#include<sys/stat.h>#include<sys/types.h>intmain(intargc,char*argv[]){structstatsb;for(inti=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");}return0;}