Skip to content

doc: improve fs.StatFs property descriptions and add examples #62712

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marcelsafin wants to merge 1 commit into
base: main
Choose a base branch
from
+45 −7
Open

doc: improve fs.StatFs property descriptions and add examples #62712

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 45 additions & 7 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7926,6 +7926,35 @@ StatFs {
}
```

To calculate disk space from a `StatFs` object, multiply the block count
properties by the fundamental block size (`statfs.frsize`) to convert
them to bytes. Pass `{ bigint: true }` to avoid loss of precision on
large file systems:

Comment on lines +7929 to +7933
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

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

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 uses AI. Check for mistakes.
```mjs
import { statfs } from 'node:fs/promises';

const stats = await statfs('/', { bigint: true });
const blockSize = stats.frsize;

console.log(`Total: ${stats.blocks * blockSize} bytes`);
console.log(`Free: ${stats.bfree * blockSize} bytes`);
console.log(`Available: ${stats.bavail * blockSize} bytes`);
```

```cjs
const { statfs } = require('node:fs');

statfs('/', { bigint: true }, (err, stats) => {
if (err) throw err;
const blockSize = stats.frsize;

console.log(`Total: ${stats.blocks * blockSize} bytes`);
console.log(`Free: ${stats.bfree * blockSize} bytes`);
console.log(`Available: ${stats.bavail * blockSize} bytes`);
});
```

#### `statfs.bavail`

<!-- YAML
Expand All @@ -7936,7 +7965,8 @@ added:

* Type: {number|bigint}

Free blocks available to unprivileged users.
Free blocks available to unprivileged users. Unlike [`statfs.bfree`][],
this value excludes blocks reserved for privileged processes.

#### `statfs.bfree`

Expand All @@ -7948,7 +7978,9 @@ added:

* Type: {number|bigint}

Free blocks in file system.
Free blocks in file system, including blocks reserved for privileged
processes. See [`statfs.bavail`][] for the count available to
unprivileged users.

#### `statfs.blocks`

Expand All @@ -7972,7 +8004,7 @@ added:

* Type: {number|bigint}

Optimal transfer block size.
Optimal transfer block size, in bytes.

#### `statfs.frsize`

Expand All @@ -7982,7 +8014,7 @@ added: REPLACEME

* Type: {number|bigint}
Comment on lines 8014 to 8015
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

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

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 uses AI. Check for mistakes.

Comment on lines 8014 to 8016
Copy link

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

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

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 uses AI. Check for mistakes.
Fundamental file system block size.
Fundamental file system block size, in bytes.
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

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

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 uses AI. Check for mistakes.

#### `statfs.ffree`

Expand All @@ -7994,7 +8026,7 @@ added:

* Type: {number|bigint}

Free file nodes in file system.
Free file nodes (inodes) in file system.

#### `statfs.files`

Expand All @@ -8006,7 +8038,7 @@ added:

* Type: {number|bigint}

Total file nodes in file system.
Total file nodes (inodes) in file system.

#### `statfs.type`

Expand All @@ -8018,7 +8050,11 @@ added:

* Type: {number|bigint}

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

### Class: `fs.Utf8Stream`

Expand Down Expand Up @@ -9052,6 +9088,8 @@ the file contents.
[`fs.rmdir()`]: #fsrmdirpath-options-callback
[`fs.stat()`]: #fsstatpath-options-callback
[`fs.statfs()`]: #fsstatfspath-options-callback
[`statfs.bavail`]: #statfsbavail
[`statfs.bfree`]: #statfsbfree
Comment on lines 9090 to +9092
Copy link

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

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

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).

Copilot uses AI. Check for mistakes.
[`fs.symlink()`]: #fssymlinktarget-path-type-callback
[`fs.utimes()`]: #fsutimespath-atime-mtime-callback
[`fs.watch()`]: #fswatchfilename-options-listener
Expand Down
Loading