Description

fs.statfs() exposes bsize (optimal I/O block size) but not frsize (fundamental filesystem block size). Per POSIX, block counts (blocks, bfree, bavail) are in units of frsize, not bsize. libuv already reads f_frsize from the kernel and stores it in uv_statfs_t — it was simply never mapped to JavaScript.

On most native filesystems bsize == frsize, so the omission was harmless. However, on FUSE mounts (e.g. Docker Desktop on macOS with VirtioFS or gRPC FUSE), they can diverge by orders of magnitude:

This causes any application computing disk space as bsize * blocks to report wildly inflated values. Real-world example: Immich photo manager shows "602 TiB of 1.8 PiB" on a 15 TB disk when running in Docker on macOS.

Changes

Adds the frsize property to the StatFs object returned by fs.statfs(), fs.statfsSync(), and fsPromises.statfs(), in both normal and bigint modes.

Files changed:

• src/node_file.h — add kFrSize to FsStatFsOffset enum
• src/node_file-inl.h — map s->f_frsize in FillStatFsArray()
• lib/internal/fs/utils.js — add frsize to StatFs class and binding
• doc/api/fs.md — document the new field
• test/parallel/test-fs-statfs.js — include frsize in property checks
• test/parallel/test-fs-promises.js — include frsize in type assertions

Notes

• On Linux, libuv sets f_frsize from the kernel's statfs.f_frsize
• On non-Linux (macOS, etc.), libuv falls back to f_frsize = f_bsize, so this is always populated
• This is a semver-minor addition (new property on existing object)