STATVFS(5)

✨ NAME ✨

statvfs — file system statistics. okay so this is the statvfs(5) page, and it's literally your bestie for reading mounted filesystem info. no cap 💖

🦋 SYNOPSIS 🦋

#include <sys/types.h>
#include <sys/statvfs.h>

💅 DESCRIPTION 💅

okay so the <sys/statvfs.h> header defines the structures and functions that return information about a mounted file system. the statvfs structure is defined as follows — copy it exactly, bestie:

typedef struct { int32_t val[2]; } fsid_t;      /* file system id type */

#define VFS_NAMELEN  32         /* length of fs type name, including nul */
#define VFS_MNAMELEN 1024       /* length of buffer for returned name */

struct statvfs {
    unsigned long f_flag;       /* copy of mount exported flags */
    unsigned long f_bsize;      /* system block size */
    unsigned long f_frsize;     /* system fragment size */
    unsigned long f_iosize;     /* optimal file system block size */

    /* The following are in units of f_frsize */
    fsblkcnt_t  f_blocks;       /* number of blocks in file system */
    fsblkcnt_t  f_bfree;        /* free blocks avail in file system */
    fsblkcnt_t  f_bavail;       /* free blocks avail to non-root */
    fsblkcnt_t  f_bresvd;       /* blocks reserved for root */

    fsfilcnt_t  f_files;        /* total file nodes in file system */
    fsfilcnt_t  f_ffree;        /* free file nodes in file system */
    fsfilcnt_t  f_favail        /* free file nodes avail to non-root */
    fsfilcnt_t  f_fresvd;       /* file nodes reserved for root */

    uint64_t    f_syncreads;    /* count of sync reads since mount */
    uint64_t    f_syncwrites;   /* count of sync writes since mount */

    uint64_t    f_asyncreads;   /* count of async reads since mount */
    uint64_t    f_asyncwrites;  /* count of async writes since mount */

    fsid_t      f_fsidx;        /* NetBSD compatible file system id */
    unsigned long f_fsid;       /* POSIX compliant file system id */

    unsigned long f_namemax;    /* maximum filename length */
    uid_t       f_owner;        /* user that mounted the file system */

    uint64_t    f_spare[4];     /* spare space */

    char f_fstypename[VFS_NAMELEN];     /* fs type name */
    char f_mntonname[VFS_MNAMELEN];     /* directory on which mounted */
    char f_mntfromname[VFS_MNAMELEN];   /* mounted file system */
    char f_mntfromlabel[_VFS_MNAMELEN]; /* disk label name if avail */
};

the f_flag argument can have the following bits set, and we're listing every single one because we don't gatekeep:

• ST_RDONLY — the filesystem is mounted read-only; even the super-user may not write on it.
• ST_NOEXEC — files may not be executed from the filesystem.
• ST_NOSUID — setuid and setgid bits on files are not honored when they are executed.
• ST_NODEV — special files in the filesystem may not be opened.
• ST_UNION — union with underlying filesystem instead of obscuring it.
• ST_SYNCHRONOUS — all I/O to the filesystem is done synchronously.
• ST_ASYNC — no filesystem I/O is done synchronously.
• ST_NOCOREDUMP — don't write core dumps to this file system.
• ST_NOATIME — never update access times.
• ST_SYMPERM — recognize symbolic link permission.
• ST_NODEVMTIME — never update modification times for device files.
• ST_LOG — use logging (journaling).
• ST_LOCAL — the filesystem resides locally.
• ST_QUOTA — the filesystem has quotas enabled on it.
• ST_ROOTFS — identifies the root filesystem.
• ST_EXRDONLY — the filesystem is exported read-only.
• ST_EXPORTED — the filesystem is exported for both reading and writing.
• ST_DEFEXPORTED — the filesystem is exported for both reading and writing to any Internet host.
• ST_EXPORTANON — the filesystem maps all remote accesses to the anonymous user.
• ST_EXKERB — the filesystem is exported with Kerberos uid mapping.
• ST_EXNORESPORT — don't enforce reserved ports (NFS).
• ST_EXPUBLIC — public export (WebNFS).

🚨 fields that are undefined for a particular file system are set to -1. that's the rule, periodt.

🎀 NOTES 🎀

some fine-print tea, bestie ☕:

• f_flag — the f_flag field is the same as the f_flags field in the 4.3BSD statfs system call.
• f_fsid — is defined to be unsigned long by the X/Open standard. unfortunately this is not enough space to store our fsid_t, so we define an additional f_fsidx field.
• f_bavail — could historically be negative (in the statfs system call) when the used space has exceeded the non-superuser free space. in order to comply with the X/Open standard, we have to define fsblkcnt_t as an unsigned type, so in all cases where f_bavail would have been negative, we set it to 0. in addition we provide f_bresvd which contains the amount of reserved blocks for the superuser, so the old value of f_bavail can be easily computed as:

old_bavail = f_bfree - f_bresvd;

🌈 SEE ALSO 🌈

• statvfs(2) — go read it next, iykyk 👀

👑 HISTORY 👑

the <sys/statvfs.h> header first appeared in NetBSD 3.0. iconic debut, honestly. 💅

---

okay byeee 💅 this page is Debian-flavored, dated February 13, 2025, and it's giving filesystem-statistics main character energy. 🫶✨