From ad50ab2cf90a1c731ee6eb32b1f23e9b5e7fd37d Mon Sep 17 00:00:00 2001 From: Harshit Date: Sun, 15 Mar 2026 16:46:05 +0530 Subject: [PATCH 1/3] doc: clarify fs.StatFs field descriptions Improve documentation for the fs.StatFs class fields: - statfs.bsize: clarify that the block size is in bytes - statfs.bavail: explain it returns free blocks for unprivileged users and how to calculate available space in bytes - statfs.bfree: explain it includes reserved blocks and how to calculate total free space in bytes - statfs.blocks: explain how to calculate total filesystem size - statfs.files and statfs.ffree: explain inodes and their importance - statfs.type: explain filesystem magic numbers and Windows behavior Add ESM and CJS usage examples showing how to calculate total, free, and available disk space from the StatFs object. Refs: https://github.com/nodejs/node/issues/50749 --- doc/api/fs.md | 60 +++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 53 insertions(+), 7 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 8481a6458faf45..f2f8619ba44642 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -7654,6 +7654,39 @@ StatFs { } ``` +The following example shows how to calculate disk space information from a +`StatFs` object. The total, free, and available space in bytes can be +calculated by multiplying the respective block counts by the block size +(`bsize`). + +```mjs +import { statfs } from 'node:fs/promises'; + +const stats = await statfs('/'); +const totalSpace = stats.blocks * stats.bsize; +const freeSpace = stats.bfree * stats.bsize; +const availableSpace = stats.bavail * stats.bsize; + +console.log(`Total: ${totalSpace / (1024 ** 3)} GiB`); +console.log(`Free: ${freeSpace / (1024 ** 3)} GiB`); +console.log(`Available: ${availableSpace / (1024 ** 3)} GiB`); +``` + +```cjs +const { statfs } = require('node:fs'); + +statfs('/', (err, stats) => { + if (err) throw err; + const totalSpace = stats.blocks * stats.bsize; + const freeSpace = stats.bfree * stats.bsize; + const availableSpace = stats.bavail * stats.bsize; + + console.log(`Total: ${totalSpace / (1024 ** 3)} GiB`); + console.log(`Free: ${freeSpace / (1024 ** 3)} GiB`); + console.log(`Available: ${availableSpace / (1024 ** 3)} GiB`); +}); +``` + #### `statfs.bavail`