From f82c05786d2f324289a38412c6820c3392828c01 Mon Sep 17 00:00:00 2001
From: Turan Almammadov <16321061+turanalmammadov@users.noreply.github.com>
Date: Tue, 24 Feb 2026 17:36:51 +0400
Subject: [PATCH] doc: improve fs.StatFs field descriptions and add usage
 examples

Addresses the gaps reported in #50749:

*  - explicitly state the unit is bytes, which is
  non-obvious because the other fields are measured in *blocks*.

*  /  - explain the difference between
  the two (superuser-reserved blocks), and add a code example showing
  how to multiply by bsize to get available bytes.

*  - add a code example that computes total, used, and
  available space in gigabytes from the three block-count fields.

*  /  - explain that these measure inodes,
  not bytes; add a code example showing how to calculate inode usage.

*  - explain that the value is a numeric OS-level file
  system identifier; point to the canonical header files for Linux
  (<linux/magic.h>) and macOS (<sys/mount.h>); note that the value is
  platform-specific and always 0 on Windows; add a code snippet that
  prints the value in hex for easier cross-referencing.

All examples are provided in both ESM and CJS variants where applicable.

Fixes: #50749
Co-authored-by: Cursor <cursoragent@cursor.com>
---
 doc/api/fs.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 84 insertions(+), 7 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 66d29bc80fbf18..d1775f4db97519 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7656,7 +7656,28 @@ added:
 
 * Type: {number|bigint}
 
-Free blocks available to unprivileged users.
+Free blocks available to unprivileged users (non-root processes). This value
+may be less than `statfs.bfree` when the file system reserves blocks for the
+superuser.
+
+Multiply by `statfs.bsize` to obtain the available space in bytes:
+
+```mjs
+import { statfs } from 'node:fs/promises';
+
+const stats = await statfs('/');
+const availableBytes = stats.bavail * stats.bsize;
+console.log(`Available space: ${(availableBytes / 1024 ** 3).toFixed(2)} GB`);
+```
+
+```cjs
+const { statfs } = require('node:fs/promises');
+
+statfs('/').then((stats) => {
+  const availableBytes = stats.bavail * stats.bsize;
+  console.log(`Available space: ${(availableBytes / 1024 ** 3).toFixed(2)} GB`);
+});
+```
 
 #### `statfs.bfree`
 
@@ -7668,7 +7689,11 @@ added:
 
 * Type: {number|bigint}
 
-Free blocks in file system.
+Free blocks in the file system, including blocks reserved for the superuser.
+To get the space available to normal (non-privileged) users, use
+`statfs.bavail` instead.
+
+Multiply by `statfs.bsize` to obtain the free space in bytes.
 
 #### `statfs.blocks`
 
@@ -7680,7 +7705,21 @@ added:
 
 * Type: {number|bigint}
 
-Total data blocks in file system.
+Total data blocks in the file system. Multiply by `statfs.bsize` to get the
+total capacity of the file system in bytes:
+
+```mjs
+import { statfs } from 'node:fs/promises';
+
+const stats = await statfs('/');
+const totalBytes = stats.blocks * stats.bsize;
+const usedBytes = (stats.blocks - stats.bfree) * stats.bsize;
+const availableBytes = stats.bavail * stats.bsize;
+
+console.log(`Total:     ${(totalBytes / 1024 ** 3).toFixed(2)} GB`);
+console.log(`Used:      ${(usedBytes / 1024 ** 3).toFixed(2)} GB`);
+console.log(`Available: ${(availableBytes / 1024 ** 3).toFixed(2)} GB`);
+```
 
 #### `statfs.bsize`
 
@@ -7692,7 +7731,17 @@ added:
 
 * Type: {number|bigint}
 
-Optimal transfer block size.
+The optimal transfer block size for the file system, **in bytes**. All
+block-count fields (`blocks`, `bfree`, `bavail`) must be multiplied by this
+value to convert them from blocks to bytes.
+
+```mjs
+import { statfs } from 'node:fs/promises';
+
+const { bsize, bavail } = await statfs('/tmp');
+const availableBytes = bavail * bsize;  // bsize is in bytes
+console.log(`Free space in /tmp: ${availableBytes} bytes`);
+```
 
 #### `statfs.ffree`
 
@@ -7704,7 +7753,9 @@ added:
 
 * Type: {number|bigint}
 
-Free file nodes in file system.
+Free file nodes (inodes) in the file system. Each file, directory, and
+symbolic link on the file system consumes one inode. When this value reaches
+zero, no new files can be created even if disk space is available.
 
 #### `statfs.files`
 
@@ -7716,7 +7767,17 @@ added:
 
 * Type: {number|bigint}
 
-Total file nodes in file system.
+Total number of file nodes (inodes) in the file system. The number of
+currently used inodes can be derived as `statfs.files - statfs.ffree`.
+
+```mjs
+import { statfs } from 'node:fs/promises';
+
+const stats = await statfs('/');
+const usedInodes = stats.files - stats.ffree;
+const inodeUsagePct = ((usedInodes / stats.files) * 100).toFixed(1);
+console.log(`Inode usage: ${inodeUsagePct}%`);
+```
 
 #### `statfs.type`
 
@@ -7728,7 +7789,23 @@ added:
 
 * Type: {number|bigint}
 
-Type of file system.
+The numeric identifier of the file system type as reported by the operating
+system. This is the value of the `f_type` field in the POSIX `statvfs`/`statfs`
+structure. Common values on Linux are defined in `<linux/magic.h>` (for example
+`0x4d44` for FAT, `0xef53` for ext2/3/4, `0x5346544e` for NTFS).
+
+On macOS the values come from `<sys/mount.h>`. On Windows this field is always
+`0`.
+
+The value is operating-system-specific and not portable across platforms.
+
+```mjs
+import { statfs } from 'node:fs/promises';
+
+const { type } = await statfs('/');
+// On Linux, 0xef53 (61267) indicates an ext2/3/4 file system.
+console.log(`File system type id: 0x${type.toString(16)}`);
+```
 
 ### Class: `fs.Utf8Stream`