Stat (system call)

Unix system call for querying file metadata

`stat` command line

`stat()` 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 (`ls -l`)
* atime: when last accessed (`ls -lu`)
* ctime: when last status changed (`ls -lc`)

`stat()` 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.[1]

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.[2]

## Functions

[edit]

The C POSIX library header sys/stat.h, found on POSIX and other Unix-like operating systems, declares `stat()` 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);

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 functions was extended to support large files. Functions `stat64()`, `lstat64()` and `fstat64()` load information into `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 to 64, the 64-bit functions are available as the original names.

## Data structure

[edit]

The metadata structure is defined in the sys/stat.h header. The following shows the base fields, but an implementation is free to define additional fields:[3]

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;

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`.[3]

Fields include:

* `st_dev` – identifier of device containing file
* `st_ino` – inode number
* `st_mode` – a bit field containing file access modes and special file type; see 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` – preferred block 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 of `DEV_BSIZE` (usually 512 bytes).

## Example

[edit]

This section may be confusing or unclear to readers. Please help clarify the section. There might be a discussion about this on the talk page. (January 2023) (Learn how and when to remove this message)

|

An example C application that logs information about each path passed via the command-line. It uses stat() to query the system for the information.

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

#include <sys/types.h>
#include <pwd.h>
#include <grp.h>
#include <sys/stat.h>

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

struct stat sb;
struct passwd *pwuser;
struct group *grpnam;

if (argc < 2)

fprintf(stderr, "Usage: %s: file ...\n", argv[0]);
exit(EXIT_FAILURE);

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

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

perror("stat()");
exit(EXIT_FAILURE);

if (NULL == (pwuser = getpwuid(sb.st_uid)))

perror("getpwuid()");
exit(EXIT_FAILURE);

if (NULL == (grpnam = getgrgid(sb.st_gid)))

perror("getgrgid()");
exit(EXIT_FAILURE);

printf("%s:\n", argv[i]);
printf("\tinode: %u\n", sb.st_ino);
printf("\towner: %u (%s)\n", sb.st_uid, pwuser->pw_name);
printf("\tgroup: %u (%s)\n", sb.st_gid, grpnam->gr_name);
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); /* you may use %lld */
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;

## References

[edit]

1. ^ McIlroy, M. D. (1987). A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986 (PDF) (Technical report). CSTR. Bell Labs. 139.
2. ^ tee, file, stat, find- correction - linuxchix.org - Wed Mar 10 11:04:07 EST 2004 (archived on April 30, 2006)
3. ^ a b Stevens & Rago 2013, p. 94.
4. ^ "<sys/stat.h>". The Open Group Base Specifications Issue 6—IEEE Std 1003.1, 2004 Edition. The Open Group. 2004.

## External links

[edit]

* 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.
* Stevens, W. Richard; Rago, Stephen A. (May 24, 2013). Advanced Programming in the UNIX Environment (Third ed.). Addison-Wesley Professional. ISBN 978-0321637734. Retrieved February 27, 2015.