stat(2)

Numbers by call, from the ledger and cross-checked against the cached kernel tables (syscall_64.tbl, syscall_32.tbl, syscall_arm.tbl, syscall_generic.tbl):

Layout note for the merge step: the domain hub splits this family into rows pointing at stat.md, fstat.md, lstat.md, and fstatat.md; this single page covers the whole man2/stat.2 family (stat, fstat, lstat, fstatat and the *64 twins), with stat/lstat/fstat having no arm64-generic slots (glibc reaches them via newfstatat 79, matching man2/stat.2’s strace observation) and the 32-bit ABIs carrying stat64/fstat64/lstat64/fstatat64 for large files (2.4).

Purpose

These calls return information about a file into a struct stat: identity (st_dev, st_ino), type and permissions (st_mode), links and ownership (st_nlink, st_uid, st_gid), device ID for special files (st_rdev), size in bytes (st_size), preferred I/O block size (st_blksize), allocated 512-byte blocks (st_blocks), and nanosecond timestamps st_atim, st_mtim, st_ctim (since kernel 2.5.48; POSIX.1-2008 names). stat() and fstatat() follow symlinks; lstat() reports on the link itself; fstat() takes an already-open descriptor, so it needs no path permissions and is the way to stat an O_PATH descriptor via fstatat’s AT_EMPTY_PATH. fstatat() generalizes all three: dirfd-relative lookup with the AT_* flags. Field layout varies across architectures and the structure has gone through three kernel-internal generations (__old_kernel_stat, stat, stat64) that glibc hides by calling the newest available call and repacking; on 64-bit systems there is a single call (man2/stat.2 C library/kernel differences).

Synopsis

#include <sys/stat.h>
int stat(const char *restrict pathname, struct stat *restrict statbuf);
int fstat(int fd, struct stat *statbuf);
int lstat(const char *restrict pathname, struct stat *restrict statbuf);

#include <fcntl.h>      /* Definition of AT_* constants */
#include <sys/stat.h>
int fstatat(int dirfd, const char *restrict pathname,
            struct stat *restrict statbuf, int flags);

Arguments and behavior

Return value and errors

0 on success; on error -1 and errno: EACCES (search permission denied on a path prefix), EBADF (fstat: fd not valid; fstatat: relative pathname with bad dirfd), EFAULT (bad statbuf/pathname address), EINVAL (fstatat: invalid flag), ELOOP, ENAMETOOLONG, ENOENT (missing component or dangling symlink; empty pathname without AT_EMPTY_PATH), ENOMEM, ENOTDIR (path prefix component; fstatat: non-directory dirfd with relative pathname), EOVERFLOW (size, inode number, or block count does not fit the 32-bit off_t/ino_t/blkcnt_t – the classic case is a >2 GiB file stat’ed by a 32-bit program compiled without -D_FILE_OFFSET_BITS=64).

Flags and constants

AT_* flags for fstatat are tabled under Arguments and behavior; values live in /usr/include/linux/fcntl.h (AT_SYMLINK_NOFOLLOW 0x100, AT_EMPTY_PATH 0x1000) and are shared with the other *at() calls. statx() (statx.md) is the mask-driven superset with creation time, mount IDs, and atomic-write limits.

Security and notes

• No permission on the target file is needed; only search permission on the path prefix directories (man2/stat.2).
• TOCTOU discipline: stat() followed by open() races with renames and symlink swaps; prefer fstat() on the descriptor actually used, and openat()-relative traversal for path component isolation.
• st_blocks/st_blksize interpretations vary across systems and even across NFS mounts (man2/stat.2 CONFORMING TO).
• Fields may come from different moments under concurrent modification (man2/stat.2 Note) – a stat() can report the old st_mode with the new st_uid.
• lstat() on a symlink: POSIX.1-2008 requires all fields except the mode bits to be valid; POSIX.1-2001 only required st_size and the file type.
• AT_EMPTY_PATH + O_PATH dirfd is the no-permission stat idiom noted on open.md (O_PATH section).

References

• man2/stat.2 in the cached man-pages tree (dated 2021-08-27); .so aliases fstat.2, lstat.2, fstatat.2 (and newfstatat.2 via fstatat.2).
• Constants: /usr/include/linux/fcntl.h (AT_*); struct stat from glibc <sys/stat.h>.
• Syscalls ledger rows SC-stat, SC-fstat, SC-lstat, SC-stat64, SC-fstat64, SC-lstat64, SC-newfstatat, SC-fstatat64; siblings statx, open, lseek; domain hub.