Skip to content
Tutorials Center
My learning

Topics

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.

C
#include <sys/stat.h>

struct stat st;
if (stat("notes.txt", &st) == 0) { /* st.st_size, st.st_mode, ... */ }

Try it

C Size and type of a file and a directory

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.

C stat vs lstat on a symbolic link, and missing files

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

C
#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 with st.st_mode == S_IFREG, because the mode also holds permission bits.
  • st_size is off_t, which can be 64 bits wide. Cast to long long for printf, as the examples do. Sparse files can have a large st_size but few st_blocks.
  • Checking with stat and then opening is a race: the file can change in between. Open first, then call fstat on the descriptor.
  • stat on 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 process umask reduces the mode requested at creation, so do not assume 0666 after fopen("w").
  • Never rely on st_atime: many file systems are mounted with noatime or relatime.
  • fstatat resolves relative paths against a directory descriptor, and statx (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 file fstat is cheaper than lseek to the end and back.