From c848da39913db1b39f187b21d57f26da66c82e70 Mon Sep 17 00:00:00 2001
From: verycosy <verycosy@kakao.com>
Date: Mon, 16 Mar 2026 22:31:00 +0900
Subject: [PATCH] fs: expose frsize field in statfs

Expose `f_frsize` from libuv's `uv_statfs_t` as `statfs.frsize`.

Per POSIX, `f_blocks`, `f_bfree`, and `f_bavail` are expressed in
units of `f_frsize`, not `f_bsize`. On most filesystems the two
values are typically equal, but some filesystem drivers report a
different `f_bsize`, making it impossible to compute accurate disk
usage without `frsize`.

Refs: https://github.com/libuv/libuv/issues/4983
---
 doc/api/fs.md                     | 12 ++++++++++++
 lib/internal/fs/utils.js          |  5 +++--
 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, 19 insertions(+), 3 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 8481a6458faf45..5cea7f571e00b4 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7632,6 +7632,7 @@ numeric values will be `bigint` instead of `number`.
 StatFs {
   type: 1397114950,
   bsize: 4096,
+  frsize: 4096,
   blocks: 121938943,
   bfree: 61058895,
   bavail: 61058895,
@@ -7646,6 +7647,7 @@ StatFs {
 StatFs {
   type: 1397114950n,
   bsize: 4096n,
+  frsize: 4096n,
   blocks: 121938943n,
   bfree: 61058895n,
   bavail: 61058895n,
@@ -7702,6 +7704,16 @@ added:
 
 Optimal transfer block size.
 
+#### `statfs.frsize`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {number|bigint}
+
+Fundamental file system block size.
+
 #### `statfs.ffree`
 
 <!-- YAML
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index e25242d6061f16..98e7b303e1091e 100644
--- a/lib/internal/fs/utils.js
+++ b/lib/internal/fs/utils.js
@@ -571,9 +571,10 @@ function getStatsFromBinding(stats, offset = 0) {
 }
 
 class StatFs {
-  constructor(type, bsize, blocks, bfree, bavail, files, ffree) {
+  constructor(type, bsize, frsize, blocks, bfree, bavail, files, ffree) {
     this.type = type;
     this.bsize = bsize;
+    this.frsize = frsize;
     this.blocks = blocks;
     this.bfree = bfree;
     this.bavail = bavail;
@@ -584,7 +585,7 @@ class StatFs {
 
 function getStatFsFromBinding(stats) {
   return new StatFs(
-    stats[0], stats[1], stats[2], stats[3], stats[4], stats[5], stats[6],
+    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..e0fc86bedc741d 100644
--- a/src/node_file-inl.h
+++ b/src/node_file-inl.h
@@ -153,6 +153,7 @@ void FillStatFsArray(AliasedBufferBase<NativeT, V8T>* fields,
 
   SET_FIELD(kType, s->f_type);
   SET_FIELD(kBSize, s->f_bsize);
+  SET_FIELD(kFrSize, s->f_frsize);
   SET_FIELD(kBlocks, s->f_blocks);
   SET_FIELD(kBFree, s->f_bfree);
   SET_FIELD(kBAvail, s->f_bavail);
diff --git a/src/node_file.h b/src/node_file.h
index 2213d590659595..61d1bc432adcfb 100644
--- a/src/node_file.h
+++ b/src/node_file.h
@@ -44,6 +44,7 @@ constexpr size_t kFsStatsBufferLength =
 enum class FsStatFsOffset {
   kType = 0,
   kBSize,
+  kFrSize,
   kBlocks,
   kBFree,
   kBAvail,
diff --git a/test/parallel/test-fs-promises.js b/test/parallel/test-fs-promises.js
index 36112d6fb60035..07f01187e89b71 100644
--- a/test/parallel/test-fs-promises.js
+++ b/test/parallel/test-fs-promises.js
@@ -89,6 +89,7 @@ function verifyStatFsObject(stat, isBigint = false) {
   assert.strictEqual(typeof stat, 'object');
   assert.strictEqual(typeof stat.type, valueType);
   assert.strictEqual(typeof stat.bsize, valueType);
+  assert.strictEqual(typeof stat.frsize, valueType);
   assert.strictEqual(typeof stat.blocks, valueType);
   assert.strictEqual(typeof stat.bfree, valueType);
   assert.strictEqual(typeof stat.bavail, valueType);
diff --git a/test/parallel/test-fs-statfs.js b/test/parallel/test-fs-statfs.js
index 411afa361d7620..4ff66a7d7c0f63 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', 'frsize', 'blocks', 'bfree', 'bavail', 'files', 'ffree',
   ].forEach((k) => {
     assert.ok(Object.hasOwn(statfs, k));
     assert.strictEqual(typeof statfs[k], valueType,