From cd87e8ac76d60f786dbbdb92169e1ef7ed32d729 Mon Sep 17 00:00:00 2001
From: justinian <juicecultus@gmail.com>
Date: Sun, 29 Mar 2026 17:03:04 +0100
Subject: [PATCH] fs: expose frsize field in statfs results
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 doc/api/fs.md                     | 20 ++++++++++++++++++--
 lib/internal/fs/utils.js          |  4 +++-
 src/node_file-inl.h               |  1 +
 src/node_file.h                   |  1 +
 test/parallel/test-fs-promises.js |  1 +
 test/parallel/test-fs-statfs.js   |  2 +-
 6 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 6330a921732f46..4adbad564b3acf 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7899,7 +7899,8 @@ StatFs {
   bfree: 61058895,
   bavail: 61058895,
   files: 999,
-  ffree: 1000000
+  ffree: 1000000,
+  frsize: 4096
 }
 ```
 
@@ -7913,7 +7914,8 @@ StatFs {
   bfree: 61058895n,
   bavail: 61058895n,
   files: 999n,
-  ffree: 1000000n
+  ffree: 1000000n,
+  frsize: 4096n
 }
 ```
 
@@ -7989,6 +7991,20 @@ added:
 
 Total file nodes in file system.
 
+#### `statfs.frsize`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number|bigint}
+
+Fundamental file system block size. This is the unit in which `blocks`,
+`bfree`, and `bavail` are counted. On most file systems this equals `bsize`,
+but on FUSE mounts (e.g. Docker Desktop on macOS using VirtioFS) they can
+differ. Use `frsize` (not `bsize`) when calculating disk space from block
+counts.
+
 #### `statfs.type`
 
 <!-- YAML
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index e25242d6061f16..13913c6fd56a33 100644
--- a/lib/internal/fs/utils.js
+++ b/lib/internal/fs/utils.js
@@ -571,7 +571,7 @@ function getStatsFromBinding(stats, offset = 0) {
 }
 
 class StatFs {
-  constructor(type, bsize, blocks, bfree, bavail, files, ffree) {
+  constructor(type, bsize, blocks, bfree, bavail, files, ffree, frsize) {
     this.type = type;
     this.bsize = bsize;
     this.blocks = blocks;
@@ -579,12 +579,14 @@ class StatFs {
     this.bavail = bavail;
     this.files = files;
     this.ffree = ffree;
+    this.frsize = frsize;
   }
 }
 
 function getStatFsFromBinding(stats) {
   return new StatFs(
     stats[0], stats[1], stats[2], stats[3], stats[4], stats[5], stats[6],
+    stats[7],
   );
 }
 
diff --git a/src/node_file-inl.h b/src/node_file-inl.h
index 29d8a12c429cb6..7149899bd15970 100644
--- a/src/node_file-inl.h
+++ b/src/node_file-inl.h
@@ -158,6 +158,7 @@ void FillStatFsArray(AliasedBufferBase<NativeT, V8T>* fields,
   SET_FIELD(kBAvail, s->f_bavail);
   SET_FIELD(kFiles, s->f_files);
   SET_FIELD(kFFree, s->f_ffree);
+  SET_FIELD(kFrSize, s->f_frsize);
 
 #undef SET_FIELD
 }
diff --git a/src/node_file.h b/src/node_file.h
index 5d04a7d4dd6af3..4b5a15a035384b 100644
--- a/src/node_file.h
+++ b/src/node_file.h
@@ -49,6 +49,7 @@ enum class FsStatFsOffset {
   kBAvail,
   kFiles,
   kFFree,
+  kFrSize,
   kFsStatFsFieldsNumber
 };
 
diff --git a/test/parallel/test-fs-promises.js b/test/parallel/test-fs-promises.js
index 36112d6fb60035..2a3c052b24b984 100644
--- a/test/parallel/test-fs-promises.js
+++ b/test/parallel/test-fs-promises.js
@@ -94,6 +94,7 @@ function verifyStatFsObject(stat, isBigint = false) {
   assert.strictEqual(typeof stat.bavail, valueType);
   assert.strictEqual(typeof stat.files, valueType);
   assert.strictEqual(typeof stat.ffree, valueType);
+  assert.strictEqual(typeof stat.frsize, valueType);
 }
 
 async function getHandle(dest) {
diff --git a/test/parallel/test-fs-statfs.js b/test/parallel/test-fs-statfs.js
index 411afa361d7620..e6858f5118e012 100644
--- a/test/parallel/test-fs-statfs.js
+++ b/test/parallel/test-fs-statfs.js
@@ -7,7 +7,7 @@ function verifyStatFsObject(statfs, isBigint = false) {
   const valueType = isBigint ? 'bigint' : 'number';
 
   [
-    'type', 'bsize', 'blocks', 'bfree', 'bavail', 'files', 'ffree',
+    'type', 'bsize', 'blocks', 'bfree', 'bavail', 'files', 'ffree', 'frsize',
   ].forEach((k) => {
     assert.ok(Object.hasOwn(statfs, k));
     assert.strictEqual(typeof statfs[k], valueType,