statvfs(3)

💖 statvfs(3) 💖

okay bestie, welcome to the <sys/statvfs.h> corner of the Library Functions Manual — this is statvfs(3) and her lil sibling fstatvfs(3), and they are literally the glow-up you need when you wanna know how much room is left on a filesystem. no cap. 🦋

---

✨ NAME ✨

statvfs, fstatvfs — get filesystem statistics 🌸

📚 LIBRARY 📚

Standard C library (libc, -lc) 💅

🎀 SYNOPSIS 🎀

#include <sys/statvfs.h>

int statvfs(const char *restrict path, struct statvfs *restrict buf);
int fstatvfs(int fd, struct statvfs *buf);

🫶 DESCRIPTION 🫶

so statvfs() hands you the tea about a mounted filesystem. path is the pathname of any file inside that mounted filesystem (yes, literally any file in there, she doesn't need the mountpoint itself, iykyk). and buf is a pointer to a statvfs structure, which looks approximately like this:

struct statvfs {
    unsigned long  f_bsize;    /* Filesystem block size */
    unsigned long  f_frsize;   /* Fragment size */
    fsblkcnt_t     f_blocks;   /* Size of fs in f_frsize units */
    fsblkcnt_t     f_bfree;    /* Number of free blocks */
    fsblkcnt_t     f_bavail;   /* Number of free blocks for
                                  unprivileged users */
    fsfilcnt_t     f_files;    /* Number of inodes */
    fsfilcnt_t     f_ffree;    /* Number of free inodes */
    fsfilcnt_t     f_favail;   /* Number of free inodes for
                                  unprivileged users */
    unsigned long  f_fsid;     /* Filesystem ID */
    unsigned long  f_flag;     /* Mount flags */
    unsigned long  f_namemax;  /* Maximum filename length */
};

quick lil note about those types: fsblkcnt_t and fsfilcnt_t live in <sys/types.h>, and both of them used to be unsigned long. the more you know 💫

---

🌈 the f_flag field 🌈

so f_flag is a bit mask — it's giving "which options were used when this filesystem got mounted". it contains zero or more of these flags, and each one is a whole vibe:

• ST_MANDLOCK — mandatory locking is permitted on the filesystem (peep fcntl(2)).
• ST_NOATIME — do not update access times; see mount(2).
• ST_NODEV — access to device special files on this filesystem is disallowed. nope, not today.
• ST_NODIRATIME — do not update directory access times; see mount(2).
• ST_NOEXEC — running programs on this filesystem is disallowed.
• ST_NOSUID — the set-user-ID and set-group-ID bits are ignored by exec(3) for executable files on this filesystem.
• ST_RDONLY — this filesystem is mounted read-only. tiny lock, cute, permanent. 🔒
• ST_RELATIME — update atime relative to mtime/ctime; see mount(2).
• ST_SYNCHRONOUS — writes are synched to the filesystem immediately (see the description of O_SYNC in open(2)).

⚠️ real talk: it is unspecified whether all members of the returned struct have meaningful values on all filesystems. so don't come for me if some field is just. there. 🙈

and fstatvfs()? she serves you the exact same info, but about an open file referenced by the descriptor fd. same energy, different doorway. ✨

🔥 RETURN VALUE 🔥

• on success? zero. slay.
• on error? -1 is returned, and errno gets set to tell you what the drama was.

😭 ERRORS 😭

• EACCES — (statvfs()) search permission is denied for a component of the path prefix of path. (also go look at path_resolution(7).)
• EBADF — (fstatvfs()) fd is not a valid open file descriptor.
• EFAULT — Buf or path points to an invalid address.
• EINTR — this call was interrupted by a signal; see signal(7).
• EIO — an I/O error occurred while reading from the filesystem. 💀
• ELOOP — (statvfs()) too many symbolic links were encountered in translating path.
• ENAMETOOLONG — (statvfs()) path is too long.
• ENOENT — (statvfs()) the file referred to by path does not exist.
• ENOMEM — insufficient kernel memory was available.
• ENOSYS — the filesystem does not support this call.
• ENOTDIR — (statvfs()) a component of the path prefix of path is not a directory.
• EOVERFLOW — some values were too large to be represented in the returned struct. the numbers were simply too big for the fit, bestie. 😔

👑 ATTRIBUTES 👑

for the explanation of the terms used in this section, see attributes(7). here's the chart, but make it a bullet list:

• statvfs(), fstatvfs() — Thread safety: MT-Safe 🧚

🦋 VERSIONS 🦋

POSIX.1 only specifies ST_NOSUID and ST_RDONLY out of the f_flag field. if you want definitions of the remaining flags, you gotta define _GNU_SOURCE. manifest it, bestie. 💅

🌸 NOTES 🌸

the Linux kernel has the system calls statfs(2) and fstatfs(2) to support this library call. so yeah, she's a libc girl with a syscall backbone. iconic.

also, the glibc implementations of

pathconf(path, _PC_REC_XFER_ALIGN);
pathconf(path, _PC_ALLOC_SIZE_MIN);
pathconf(path, _PC_REC_MIN_XFER_SIZE);

respectively use the f_frsize, f_frsize, and f_bsize fields returned by a call to statvfs() with the argument path. (yes, f_frsize shows up twice. that's not me being messy, that's just the lore. 🌈)

and under Linux, f_favail is always the same as f_ffree, and there's literally no way for a filesystem to report otherwise. not a problem tho, since no filesystems with an inode root reservation exist. so we move. 🫶

⭐ STANDARDS ⭐

POSIX.1-2008. periodt.

💜 HISTORY 💜

POSIX.1-2001. throwback.

before glibc 2.13, statvfs() populated the bits of the f_flag field by scanning the mount options shown in /proc/mounts. but starting with Linux 2.6.36, the underlying statfs(2) system call provides the necessary information via the f_flags field, and since glibc 2.13, the statvfs() function will use information from that field rather than scanning /proc/mounts. character development fr fr. 📈

🌟 SEE ALSO 🌟

• statfs(2)

---

and that's the whole page, bestie!! 🎀 this was statvfs(3) from Linux man-pages 6.20, dated 2026-02-08 — go forth and check your disk space with main character energy, ily, bye!! 👑✨💖