Module sys/statfs
Filesystem statistics (statvfs) — the raw syscall boundary.
One synchronous query plus typed accessors over the buffer it fills. The
accessors exist because the buffer is the platform's own struct — a
struct statvfs on POSIX, a private shim struct on Windows — so only the
generated runtime knows where the fields are. No public std module
reports disk usage yet; tests/sys/statfs.test.yo is the only caller in
this tree.
statfs returns 0 on success, a negative errno on failure. The accessors
cannot fail; they read whatever is in the buffer.
statfs :: import("std/sys/statfs");
{ malloc, free } :: import("std/allocator").GlobalAllocator;
buf_size := statfs.statfs_buf_size();
buf := (*u8)(malloc(buf_size).unwrap());
rc := statfs.statfs((*u8)("/"), buf);
free_bytes := (statfs.statfs_bavail(buf) * statfs.statfs_bsize(buf));
free(.Some((*void)(buf)));
Stability
unstable — a caller-allocated opaque buffer with nine free functions
reading it is a layout contract, not an API, and two of those functions
can only ever answer 0 (statfs_type everywhere, plus statfs_files and
statfs_ffree on Windows). A frozen version returns a Yo struct from one
call and drops the fields no platform can fill, the way
std/sys/statx's Statx at least wraps its buffer in a type. Freezing
follows that rewrite, and a decision about whether "filesystem type"
belongs in the API at all given that nothing supplies it.
Functions
Fill buf with statistics for the filesystem CONTAINING path — POSIX
statvfs(3), not statfs(2), which is why there is no filesystem-type
field below. buf must be statfs_buf_size() bytes. Returns 0 on
success, a negative errno on failure.
path need only be some existing name on the filesystem — a directory is
fine — and it is resolved, so a symlink reports its target's filesystem.
On Windows the runtime combines GetDiskFreeSpaceExW (for the byte
totals) and GetDiskFreeSpaceW (for the cluster geometry) into its own
struct.
Parameters
| Name | Type | Notes |
|---|---|---|
path | *u8 | |
buf | *u8 |
Returns: i32
Bytes to allocate for a statfs buffer — sizeof(struct statvfs) on
POSIX, the size of the Windows shim struct there. A call rather than a
constant because only the generated runtime knows the platform's struct.
Returns: usize
Filesystem type code. Always 0, on every platform: statvfs has no
f_type field (that is statfs(2)'s, which this module does not use) and
the Windows shim leaves its slot zeroed. The accessor exists for parity
with the Linux statfs layout; do not branch on it.
Parameters
| Name | Type | Notes |
|---|---|---|
buf | *u8 |
Returns: u64
Fundamental block size in bytes (f_bsize) — the unit that blocks,
bfree and bavail are counted in, so free BYTES is bavail × bsize.
On Windows this is sectors-per-cluster × bytes-per-sector, i.e. the
cluster size.
Parameters
| Name | Type | Notes |
|---|---|---|
buf | *u8 |
Returns: u64
Total data blocks on the filesystem (f_blocks), in bsize units — the
denominator for a "disk N% full" figure.
Parameters
| Name | Type | Notes |
|---|---|---|
buf | *u8 |
Returns: u64
Free blocks (f_bfree), in bsize units — including the reserve that
only a privileged process may consume. Use bavail instead unless you
are that process.
Parameters
| Name | Type | Notes |
|---|---|---|
buf | *u8 |
Returns: u64
Free blocks available to an UNPRIVILEGED process (f_bavail), in bsize
units. This is the number that answers "can I write this file", and it is
what df's "Available" column reports.
Parameters
| Name | Type | Notes |
|---|---|---|
buf | *u8 |
Returns: u64
Total file nodes / inodes (f_files). 0 on Windows, which has no fixed
inode table, and 0 on filesystems that allocate inodes dynamically — so
treat 0 as "not reported" rather than "full".
Parameters
| Name | Type | Notes |
|---|---|---|
buf | *u8 |
Returns: u64
Free file nodes / inodes (f_ffree). 0 on Windows, and subject to the
same "0 means not reported" reading as statfs_files.
Parameters
| Name | Type | Notes |
|---|---|---|
buf | *u8 |
Returns: u64