From 6b4403edcd474533c847e8299b5cc24c60318ff0 Mon Sep 17 00:00:00 2001 From: marcelsafin <179933638+marcelsafin@users.noreply.github.com> Date: Mon, 13 Apr 2026 00:06:37 +0200 Subject: [PATCH] doc: improve fs.StatFs property descriptions and add examples 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: https://github.com/nodejs/node/issues/50749 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- doc/api/fs.md | 52 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 45 insertions(+), 7 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 94aea1032f539c..138d87218794f2 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -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: + +```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`