C Reference ยท POSIX and Systems
C stat(), fstat() and lstat() functions
Reference for stat(), fstat() and lstat(): read a file's size, type, permissions and link count, test the type with S_ISREG and S_ISDIR, and avoid common races.
stat() fills a struct stat with information about a file: its type (regular file, directory, symbolic link...), size in bytes, permission bits, owner, link count and timestamps. It is the right tool when you need metadata without opening and reading the file, for instance to check whether a path is a directory or to learn how big a buffer must be.
There are three variants. stat(path, &st) follows symbolic links, lstat(path, &st) describes the link itself, and fstat(fd, &st) works on an already open descriptor, which avoids races between the check and the use.
#include <sys/stat.h> struct stat st; if (stat("notes.txt", &st) == 0) { /* st.st_size, st.st_mode, ... */ }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
#include <sys/stat.h> int stat (const char *restrict path, struct stat *restrict buf); int lstat(const char *restrict path, struct stat *restrict buf); int fstat(int fd, struct stat *buf);
| Name | Description |
|---|---|
path |
The file to describe. |
fd |
An open file descriptor (fstat). |
buf |
The structure to fill. |
Returns: 0 on success, -1 on failure.
Errors: ENOENT (path does not exist), EACCES (search permission denied on a directory in the path), ENOTDIR, ELOOP, ENAMETOOLONG, EBADF (for fstat), EOVERFLOW.
Fields of struct stat
| Field | Meaning |
|---|---|
st_mode |
File type and permission bits (test with the S_IS... macros and S_IRUSR, S_IWUSR...) |
st_size |
Size in bytes (for a symbolic link, the length of the path it contains) |
st_nlink |
Number of hard links |
st_uid, st_gid |
Owner and group IDs |
st_mtime, st_atime, st_ctime |
Last modification, access and status-change times (time_t; nanosecond versions are in st_mtim and friends) |
st_dev, st_ino |
Device and inode: together they identify a file uniquely |
st_blocks, st_blksize |
Disk blocks used and preferred I/O size |
Usage notes
- Test the type with the macros (
S_ISREG(st.st_mode)), never withst.st_mode == S_IFREG, because the mode also holds permission bits. st_sizeisoff_t, which can be 64 bits wide. Cast tolong longforprintf, as the examples do. Sparse files can have a largest_sizebut fewst_blocks.- Checking with
statand then opening is a race: the file can change in between. Open first, then callfstaton the descriptor. staton a file with no read permission still works as long as you can search the directories leading to it.- Print permissions in octal (
%o). The processumaskreduces the mode requested at creation, so do not assume0666afterfopen("w"). - Never rely on
st_atime: many file systems are mounted withnoatimeorrelatime. fstatatresolves relative paths against a directory descriptor, andstatx(Linux) offers more fields such as creation time.- For a simple "does it exist" test use
access(path, F_OK); for the size of an open filefstatis cheaper thanlseekto the end and back.