doc: improve fs.StatFs property descriptions and add examples by marcelsafin · Pull Request #62712 · nodejs/node

marcelsafin · 2026-04-12T22:07:34Z

Summary

Improve the fs.StatFs class documentation by addressing multiple gaps reported in #50749.

Changes

Units: Clarify that bsize and frsize values are in bytes
Examples: Add ESM and CJS examples showing how to calculate total, free, and available disk space from StatFs properties
Cross-references: Link related properties together (e.g., bavail ↔ bfree, block counts → bsize)
bavail vs bfree: Explain that bavail excludes space reserved by the OS, while bfree includes it
type: Document that it's a filesystem magic number and list common values (ext4, NTFS, tmpfs, NFS)
Inodes: Clarify that files and ffree refer to inodes

Motivation

The existing documentation only has one-line descriptions like "Free blocks in file system" without specifying units, how to use the values, or what type represents. Multiple users have reported confusion (see #50749), and several people volunteered to fix it but no PR was submitted.

Fixes: #50749

Copilot

Pull request overview

Improves the fs.StatFs documentation to clarify units/semantics of key fields and provide practical examples for calculating disk space.

Changes:

Adds ESM and CJS examples for computing total/free/available bytes from StatFs results.
Expands property descriptions (bavail, bfree, blocks, bsize, frsize, inode fields) with unit clarifications and cross-references.
Documents statfs.type as a filesystem magic number and adds common example values.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-12T22:11:31Z

doc/api/fs.md

+To calculate disk space from a `StatFs` object, multiply the block count
+properties by `statfs.bsize` (the block size in bytes):
+


The guidance here says to multiply block counts by statfs.bsize, but on POSIX bsize is the optimal transfer size; the block counts (blocks, bfree, bavail) are reported in units of the fundamental block size (frsize, and on Linux it can differ from bsize). Consider basing the example on statfs.frsize (or clearly documenting when to use frsize vs bsize).

Copilot · 2026-04-12T22:11:31Z

doc/api/fs.md

+const stats = await statfs('/');
+const byteSize = stats.bsize;
+
+console.log(`Total: ${stats.blocks * byteSize} bytes`);
+console.log(`Free:  ${stats.bfree * byteSize} bytes`);


This example uses the default number return type, but blocks * bsize/frsize can exceed Number.MAX_SAFE_INTEGER on large volumes and produce an imprecise result. Consider using statfs(path, { bigint: true }) in the example (and then keeping all arithmetic in bigint) or explicitly warning about precision limits when using number.

Copilot · 2026-04-12T22:11:31Z

doc/api/fs.md

+Free blocks available to unprivileged users. This value accounts for
+space reserved by the operating system (unlike [`statfs.bfree`][]). Use
+`statfs.bavail * statfs.bsize` to get the available space in bytes.


These byte conversion instructions use statfs.bsize, but the block counts are in units of statfs.frsize (and frsize may differ from bsize, e.g. on Linux). The formula should reference statfs.frsize (or explain why bsize is correct on the supported platforms).

Copilot · 2026-04-12T22:11:31Z

doc/api/fs.md

+Free blocks in file system, including reserved blocks that are not
+available to unprivileged users. See [`statfs.bavail`][] for the
+unreserved count. Use `statfs.bfree * statfs.bsize` to get the free
+space in bytes.


These byte conversion instructions use statfs.bsize, but the block counts are in units of statfs.frsize (and frsize may differ from bsize, e.g. on Linux). The formula should reference statfs.frsize (or explain why bsize is correct on the supported platforms).

Copilot · 2026-04-12T22:11:32Z

doc/api/fs.md

+Total data blocks in file system. Use `statfs.blocks * statfs.bsize`
+to get the total size in bytes.


This suggests statfs.blocks * statfs.bsize for total size, but block counts are in units of statfs.frsize (and frsize may differ from bsize, e.g. on Linux). Consider switching the formula to statfs.blocks * statfs.frsize (or explain the distinction).

Suggested change

Total data blocks in file system. Use `statfs.blocks * statfs.bsize`

to get the total size in bytes.

Total data blocks in file system.

Copilot · 2026-04-12T22:11:32Z

doc/api/fs.md

+Optimal transfer block size, in bytes. Multiply this value by block count
+properties (such as [`statfs.blocks`][], [`statfs.bfree`][], and
+[`statfs.bavail`][]) to convert them to bytes.


bsize is documented as the optimal transfer size, but this text also says to multiply it by blocks/bfree/bavail to convert to bytes. Those counts are in units of frsize (fundamental block size) on POSIX, so this conversion guidance is misleading on platforms where frsize !== bsize (notably Linux). Consider pointing conversions at statfs.frsize instead, and keep bsize as transfer hint.

Copilot · 2026-04-12T22:11:32Z

doc/api/fs.md

-Type of file system.
+Type of file system, as a filesystem magic number. Common values include
+`0xEF53` (ext2/ext3/ext4), `0x5346544e` (NTFS), `0x01021994` (tmpfs),
+and `0x6969` (NFS). See the statfs(2) man page for more values.


On Windows, libuv reports statfs.type as 0 (see deps/uv/src/win/fs.c), so listing common magic numbers without noting this platform behavior may confuse readers. Consider mentioning that the value is platform-dependent and may be 0 on Windows.

Suggested change

and `0x6969` (NFS). See the statfs(2) man page for more values.

and `0x6969` (NFS). The value is platform-dependent; on Windows, libuv may

report `0` instead of a filesystem-specific magic number. See the

statfs(2) man page for more values.

Copilot · 2026-04-12T22:11:32Z

doc/api/fs.md


 * Type: {number|bigint}


The statfs.frsize YAML frontmatter immediately above this section still contains added: REPLACEME, which will break the docs metadata tooling. Replace it with the actual version(s) where frsize became available (likely the same as the other StatFs fields in this section).

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-12T22:33:14Z

doc/api/fs.md

+const stats = await statfs('/', { bigint: true });
+
+console.log(`Total: ${stats.blocks * stats.bsize} bytes`);
+console.log(`Free:  ${stats.bfree * stats.bsize} bytes`);
+console.log(`Available: ${stats.bavail * stats.bsize} bytes`);


These calculations multiply by stats.bsize, but for correctness across platforms (notably Linux) the block counts should be converted using the fundamental block size (stats.frsize). Suggest switching these multiplications to use frsize (or const blockSize = stats.frsize ?? stats.bsize).

Copilot · 2026-04-12T22:33:14Z

doc/api/fs.md

+Free blocks available to unprivileged users. Unlike [`statfs.bfree`][],
+this value excludes blocks reserved for privileged processes. Use
+`statfs.bavail * statfs.bsize` to get the available space in bytes.


This sentence recommends statfs.bavail * statfs.bsize for available bytes, but bavail is a block count and should be multiplied by the fundamental block size (statfs.frsize) for correct byte conversion on platforms where bsize differs from frsize (e.g., Linux). Please update this (and the similar bfree/blocks guidance) to use frsize or a frsize ?? bsize fallback.

Copilot · 2026-04-12T22:33:14Z

doc/api/fs.md

 * Type: {number|bigint}

-Fundamental file system block size.
+Fundamental file system block size, in bytes.


The YAML metadata directly above this section still has added: REPLACEME for statfs.frsize, while the other StatFs properties list concrete versions. Please replace REPLACEME with the correct version(s) (likely matching the other statfs.* fields) to keep the documentation metadata consistent.

Copilot · 2026-04-12T22:33:14Z

doc/api/fs.md

+Type of file system. On Linux this is a filesystem magic number (for
+example, `0xEF53` for ext2/ext3/ext4). The value is platform-dependent
+and may be `0` on systems where libuv does not report it.


PR description says the statfs.type docs will list common filesystem magic values (ext4, NTFS, tmpfs, NFS), but the updated text only gives an ext2/ext3/ext4 example. Either expand this list as described (with a source/caveat) or adjust the PR description to match what’s actually documented.

Add missing information to the fs.StatFs class documentation: - Clarify that bsize and frsize values are in bytes - Add ESM and CJS examples showing how to calculate disk space - Explain the relationship between block counts and bsize - Clarify the difference between bavail (unprivileged) and bfree (total) - Document that type is a filesystem magic number with common values - Add cross-references between related properties Fixes: nodejs#50749 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-13T08:04:35Z

doc/api/fs.md


 * Type: {number|bigint}



The statfs.frsize section still has added: REPLACEME in its YAML metadata (a few lines above this property header). This placeholder should be replaced with the real version(s) to avoid breaking docs generation/versioning.

Copilot · 2026-04-13T08:04:36Z

doc/api/fs.md

 [`fs.statfs()`]: #fsstatfspath-options-callback
+[`statfs.bavail`]: #statfsbavail
+[`statfs.bfree`]: #statfsbfree


These reference definitions don’t match the link labels used above: the prose links are written as [statfs.bavail][] / [statfs.bfree][], which include backticks as part of the reference label. As written, the definitions [statfs.bavail]: ... / [statfs.bfree]: ... won’t resolve, so the cross-references will be broken. Align the definition labels with the inline references (or update the inline references accordingly).

marcelsafin · 2026-04-13T08:30:54Z

Re: link reference definitions — the definitions at lines 9091–9092 do include backticks:

[`statfs.bavail`]: #statfsbavail
[`statfs.bfree`]: #statfsbfree

This matches the inline references ([`statfs.bavail`][]) and follows the same pattern used throughout the file (e.g., [`fs.statfs()`]: #fsstatfspath-options-callback).

Re: added: REPLACEME on statfs.frsize — this is pre-existing in main (source) and will be filled in by the release tooling. It is outside the scope of this documentation PR.

Copilot AI review requested due to automatic review settings April 12, 2026 22:07

nodejs-github-bot added doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. labels Apr 12, 2026

Copilot started reviewing on behalf of marcelsafin April 12, 2026 22:08 View session

Copilot AI reviewed Apr 12, 2026

View reviewed changes

marcelsafin force-pushed the docs/improve-statfs-documentation branch from 58b8ced to f0d3619 Compare April 12, 2026 22:21

marcelsafin requested a review from Copilot April 12, 2026 22:29

Copilot started reviewing on behalf of marcelsafin April 12, 2026 22:30 View session

Copilot AI reviewed Apr 12, 2026

View reviewed changes

marcelsafin force-pushed the docs/improve-statfs-documentation branch from f0d3619 to e916e38 Compare April 12, 2026 22:35

marcelsafin force-pushed the docs/improve-statfs-documentation branch from e916e38 to 6b4403e Compare April 12, 2026 22:43

marcelsafin requested a review from Copilot April 12, 2026 22:45

Copilot started reviewing on behalf of marcelsafin April 12, 2026 22:46 View session

Copilot AI reviewed Apr 12, 2026

View reviewed changes

marcelsafin requested a review from Copilot April 13, 2026 08:00

Copilot started reviewing on behalf of marcelsafin April 13, 2026 08:01 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

		To calculate disk space from a `StatFs` object, multiply the block count
		properties by `statfs.bsize` (the block size in bytes):

		Total data blocks in file system. Use `statfs.blocks * statfs.bsize`
		to get the total size in bytes.

	Total data blocks in file system. Use `statfs.blocks * statfs.bsize`
	to get the total size in bytes.
	Total data blocks in file system.

Uh oh!

Conversation

marcelsafin commented Apr 12, 2026

Summary

Changes

Motivation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

marcelsafin commented Apr 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants