From 334064a316dad768a7e1cf92e552c20a2e2421c1 Mon Sep 17 00:00:00 2001 From: kovan Date: Fri, 13 Mar 2026 17:21:25 +0100 Subject: [PATCH] doc: clarify fs.StatFs field descriptions Clarify that bsize is in bytes and serves as the unit for the block count fields (blocks, bfree, bavail). Add "multiply by bsize" hints so users can compute sizes without guessing units. Explain that type is a file system magic number with platform-specific values. Mention that ffree/files count inodes. Fixes: https://github.com/nodejs/node/issues/50749 --- doc/api/fs.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 8481a6458faf45..11b708e8753f0c 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -7664,7 +7664,8 @@ added: * Type: {number|bigint} -Free blocks available to unprivileged users. +Free blocks available to unprivileged users. Multiply by `statfs.bsize` +to get the value in bytes. #### `statfs.bfree` @@ -7676,7 +7677,9 @@ added: * Type: {number|bigint} -Free blocks in file system. +Free blocks in file system. This includes blocks reserved for the +superuser that are not reported by `statfs.bavail`. Multiply by +`statfs.bsize` to get the value in bytes. #### `statfs.blocks` @@ -7688,7 +7691,8 @@ added: * Type: {number|bigint} -Total data blocks in file system. +Total data blocks in file system. Multiply by `statfs.bsize` to get +the total size in bytes. #### `statfs.bsize` @@ -7700,7 +7704,8 @@ added: * Type: {number|bigint} -Optimal transfer block size. +Optimal transfer block size in bytes. This value is also the unit for +the `statfs.blocks`, `statfs.bfree`, and `statfs.bavail` fields. #### `statfs.ffree` @@ -7712,7 +7717,7 @@ added: * Type: {number|bigint} -Free file nodes in file system. +Free file nodes (inodes) in file system. #### `statfs.files` @@ -7724,7 +7729,7 @@ added: * Type: {number|bigint} -Total file nodes in file system. +Total file nodes (inodes) in file system. #### `statfs.type` @@ -7736,7 +7741,11 @@ added: * Type: {number|bigint} -Type of file system. +File system type as a numeric identifier. On Linux this is the +file system magic number (e.g. `0xef53` for ext2/ext3/ext4, +`0x01021994` for tmpfs). On other platforms the value is +OS-dependent. See the `statfs(2)` man page on Linux or `statfs(2)` +on macOS for platform-specific values. ### Class: `fs.Utf8Stream`