Stat (system call)

File:Coreutils stat screenshot.png

stat command line

<syntaxhighlight lang="text" class="" style="" inline="1">stat()</syntaxhighlight> 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 <syntaxhighlight lang="text" class="" style="" inline="1">ls</syntaxhighlight> command uses this system call to retrieve timestamps:

• mtime: when last modified (<syntaxhighlight lang="text" class="" style="" inline="1">ls -l</syntaxhighlight>)
• atime: when last accessed (<syntaxhighlight lang="text" class="" style="" inline="1">ls -lu</syntaxhighlight>)
• ctime: when last status changed (<syntaxhighlight lang="text" class="" style="" inline="1">ls -lc</syntaxhighlight>)

<syntaxhighlight lang="text" class="" style="" inline="1">stat()</syntaxhighlight> 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.<ref>Template:Cite tech report</ref>

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

Functions

The C POSIX library header Template:Mono, found on POSIX and other Unix-like operating systems, declares stat() and related functions.

<syntaxhighlight lang="c"> 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 struct 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, sets errno to indicate the failure condition and returns −1.

The stat() and lstat() functions accept a path argument that specifies a file. If the path identifies a symbolic link, stat() returns attributes of the link target, whereas lstat() returns attributes of the link itself. The fstat() 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 stat64(), lstat64() and fstat64() load information into a struct 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_BITS macro is defined as 64, the 64-bit functions are available as the original names.

Data structure

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

<syntaxhighlight lang="c"> 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 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.Template:Sfn

Fields include:

• st_devTemplate:Snd identifier of device containing file
• st_inoTemplate:Snd inode number
• st_modeTemplate:Snd a bit field containing file access modes and special file type; see Unix permissions
• st_nlinkTemplate:Snd reference count of hard links
• st_uidTemplate:Snd user identifier of owner
• st_gidTemplate:Snd group identifier of owner
• st_rdevTemplate:Snd device identifier (if special file)
• st_sizeTemplate:Snd total file size, in bytes
• st_atimeTemplate:Snd time of last access
• st_mtimeTemplate:Snd time of last modification
• st_ctimeTemplate:Snd time of last status change
• st_blksizeTemplate:Snd preferred block size for file system I/O, which can depend upon both the system and the type of file system<ref>Template:Cite web</ref>
• st_blocksTemplate:Snd number of blocks allocated in multiples of DEV_BSIZE (usually 512 bytes).

Example

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

<syntaxhighlight lang="c">

1. include <stdio.h>
2. include <stdlib.h>
3. include <time.h>
4. include <sys/stat.h>
5. 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>

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.
• Template:Cite book