Skip to content

fs: expose frsize field in statfs results#62495

Open
juicecultus wants to merge 1 commit intonodejs:mainfrom
juicecultus:fs-statfs-expose-frsize
Open

fs: expose frsize field in statfs results#62495
juicecultus wants to merge 1 commit intonodejs:mainfrom
juicecultus:fs-statfs-expose-frsize

Conversation

@juicecultus
Copy link
Copy Markdown

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:

Field Value * blocks result
bsize 2,097,152 (2 MiB) 1.82 PiB
frsize 16,384 (16 KiB) 14.9 TiB

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)

Node.js 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 — it was simply not 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 differ by orders of magnitude
(bsize=2MiB vs frsize=16KiB), causing applications that compute disk
space as bsize*blocks to report wildly inflated values.

This commit adds the frsize property to the StatFs object returned by
fs.statfs(), fs.statfsSync(), and fsPromises.statfs(), in both normal
and bigint modes.
@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Mar 29, 2026
@codecov
Copy link
Copy Markdown

codecov Bot commented Mar 30, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.71%. Comparing base (bdf75a6) to head (cd87e8a).
⚠️ Report is 22 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main   #62495   +/-   ##
=======================================
  Coverage   89.71%   89.71%           
=======================================
  Files         692      692           
  Lines      213988   214042   +54     
  Branches    41054    41062    +8     
=======================================
+ Hits       191976   192026   +50     
- Misses      14086    14090    +4     
  Partials     7926     7926           
Files with missing lines Coverage Δ
lib/internal/fs/utils.js 99.68% <100.00%> (+<0.01%) ⬆️
src/node_file-inl.h 87.71% <100.00%> (+0.05%) ⬆️
src/node_file.h 78.43% <ø> (ø)

... and 35 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@jazelly jazelly added the fs Issues and PRs related to the fs subsystem / file system. label Mar 31, 2026
Comment thread src/node_file-inl.h
SET_FIELD(kBAvail, s->f_bavail);
SET_FIELD(kFiles, s->f_files);
SET_FIELD(kFFree, s->f_ffree);
SET_FIELD(kFrSize, s->f_frsize);
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks like GHA is complaining about this on some platforms.

@bo0tzz
Copy link
Copy Markdown

bo0tzz commented Apr 18, 2026

Dupe of #62277?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

c++ Issues and PRs that require attention from people who are familiar with C++. fs Issues and PRs related to the fs subsystem / file system. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants