STATFS(2)

💖 STATFS(2) — the manual page, but make it cute 💖

okay bestie, gather round, because today we're reading statfs(2) from the System Calls Manual and honestly? it ate. no cap. ✨

---

🌸 NAME 🌸

statfs — get file system statistics 💅

---

📚 LIBRARY 📚

Standard C Library (libc, -lc) 🫶

---

✨ SYNOPSIS ✨

#include <sys/param.h>
#include <sys/mount.h>

int
statfs(const char *path, struct statfs *buf);

int
fstatfs(int fd, struct statfs *buf);

---

🦋 DESCRIPTION 🦋

so the statfs() system call is literally your little spy that goes and gets info about a mounted file system. the path argument is the path name of any file within the mounted file system (any file, she's not picky 💁). and the buf argument is a pointer to a statfs structure, which is defined like this:

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

/*
 * filesystem statistics
 */

#define MFSNAMELEN      16              /* length of type name including null */
#define MNAMELEN        1024            /* size of on/from name bufs */
#define STATFS_VERSION  0x20140518      /* current version number */

struct statfs {
uint32_t f_version;             /* structure version number */
uint32_t f_type;                /* type of filesystem */
uint64_t f_flags;               /* copy of mount exported flags */
uint64_t f_bsize;               /* filesystem fragment size */
uint64_t f_iosize;              /* optimal transfer block size */
uint64_t f_blocks;              /* total data blocks in filesystem */
uint64_t f_bfree;               /* free blocks in filesystem */
int64_t  f_bavail;              /* free blocks avail to non-superuser */
uint64_t f_files;               /* total file nodes in filesystem */
int64_t  f_ffree;               /* free nodes avail to non-superuser */
uint64_t f_syncwrites;          /* count of sync writes since mount */
uint64_t f_asyncwrites;         /* count of async writes since mount */
uint64_t f_syncreads;           /* count of sync reads since mount */
uint64_t f_asyncreads;          /* count of async reads since mount */
uint64_t f_spare[10];           /* unused spare */
uint32_t f_namemax;             /* maximum filename length */
uid_t     f_owner;              /* user that mounted the filesystem */
fsid_t    f_fsid;               /* filesystem id */
char      f_charspare[80];          /* spare string space */
char      f_fstypename[MFSNAMELEN]; /* filesystem type name */
char      f_mntfromname[MNAMELEN];  /* mounted filesystem */
char      f_mntonname[MNAMELEN];    /* directory on which mounted */
};

look at her. so many fields. main character energy fr fr 👑

🎀 the flags that may be returned 🎀

• MNT_RDONLY — the file system is mounted read-only; even the superuser may not write on it. like, not even the boss. respect the boundary.
• MNT_NOEXEC — files may not be executed from the file system.
• MNT_NOSUID — setuid and setgid bits on files are not honored when they are executed.
• MNT_SYNCHRONOUS — all I/O to the file system is done synchronously.
• MNT_ASYNC — no file system I/O is done synchronously.
• MNT_SOFTDEP — soft updates being done (see ffs(7)).
• MNT_GJOURNAL — journaling with gjournal is enabled (see gjournal(8)).
• MNT_SUIDDIR — special handling of SUID bit on directories.
• MNT_UNION — union with underlying file system.
• MNT_NOSYMFOLLOW — symbolic links are not followed.
• MNT_NOCLUSTERR — read clustering is disabled.
• MNT_NOCLUSTERW — write clustering is disabled.
• MNT_MULTILABEL — Mandatory Access Control (MAC) support for individual objects (see mac(4)).
• MNT_ACLS — Access Control List (ACL) support enabled.
• MNT_LOCAL — the file system resides locally.
• MNT_QUOTA — the file system has quotas enabled on it.
• MNT_ROOTFS — identifies the root file system.
• MNT_EXRDONLY — the file system is exported read-only.
• MNT_NOATIME — updating of file access times is disabled.
• MNT_USER — the file system has been mounted by a user.
• MNT_EXPORTED — the file system is exported for both reading and writing.
• MNT_DEFEXPORTED — the file system is exported for both reading and writing to any Internet host.
• MNT_EXPORTANON — the file system maps all remote accesses to the anonymous user.
• MNT_EXKERB — the file system is exported with Kerberos uid mapping.
• MNT_EXPUBLIC — the file system is exported publicly (WebNFS).

⚠️ important bestie: fields that are undefined for a particular file system are set to -1. don't come for me, that's just the rules.

and the fstatfs() system call? she returns the same information about an open file referenced by descriptor fd. same info, different entrance, iykyk 💅

---

🍓 RETURN VALUES 🍓

upon successful completion, the value 0 is returned. otherwise, the value -1 is returned and the global variable errno is set to indicate the error. so if you see -1, check errno, that's your girl with the tea 😭

---

💀 ERRORS 💀

the statfs() system call fails if one or more of the following are true:

• [ENOTDIR] — a component of the path prefix of path is not a directory.
• [ENAMETOOLONG] — the length of a component of path exceeds 255 characters, or the length of path exceeds 1023 characters.
• [ENOENT] — the file referred to by path does not exist.
• [EACCES] — search permission is denied for a component of the path prefix of path.
• [ELOOP] — too many symbolic links were encountered in translating path.
• [EFAULT] — the buf or path argument points to an invalid address.
• [EIO] — an I/O error occurred while reading from or writing to the file system.
• [EINTEGRITY] — corrupted data was detected while reading from the file system. yikes.

the fstatfs() system call fails if one or more of the following are true:

• [EBADF] — the fd argument is not a valid open file descriptor.
• [EFAULT] — the buf argument points to an invalid address.
• [EIO] — an I/O error occurred while reading from or writing to the file system.
• [EINTEGRITY] — corrupted data was detected while reading from the file system.

---

🌈 SEE ALSO 🌈

fhstatfs(2), getfsstat(2) — go read those too, they're the friend group 🫶

---

👑 HISTORY 👑

the statfs() system call first appeared in 4.4BSD. iconic behavior, honestly. the blueprint. periodt. 💜

---

and that's the whole page bestie!! this one's from the Debian crew, dated March 30, 2020 — mwah, thank you for your service 🎀✨ go forth and stat your file systems, you've got this 💖🦋