doc: clarify fs.StatFs field descriptions#62262
Open
AkaHarshit wants to merge 2 commits intonodejs:mainfrom
Open
doc: clarify fs.StatFs field descriptions#62262AkaHarshit wants to merge 2 commits intonodejs:mainfrom
AkaHarshit wants to merge 2 commits intonodejs:mainfrom
Conversation
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: nodejs#50749
nodejs-github-bot
added
doc
Member
mertcanaltin
left a comment
mertcanaltin
left a comment
There was a problem hiding this comment.
Thanks for contributing!
doc/api/fs.md
Outdated
| * Type: {number|bigint} | ||
|
|
||
| Optimal transfer block size. | ||
| The optimal transfer block size in bytes. This value represents the fundamental |
Member
There was a problem hiding this comment.
bsize POSIX defines the optimal transfer block size, not the allocation block size. Just appending "in bytes"
doc/api/fs.md
Outdated
| Type of file system. | ||
| A numeric identifier for the file system type. This value is a filesystem magic | ||
| number set by the operating system kernel, such as `0xEF53` for ext4 or | ||
| `0x01021994` for tmpfs on Linux. On Windows, this value is `0`. |
Member
There was a problem hiding this comment.
Not only Windows return 0 , libuv also returns 0 on Solaris, OpenBSD, NetBSD, Haiku, and QNX, consider changing "On Windows" to "On some platforms"
Suggested change
| `0x01021994` for tmpfs on Linux. On Windows, this value is `0`. | |
| `0x01021994` for tmpfs on Linux. On some platforms (e.g., Windows, Solaris), this value is `0`. |
- Simplify bsize description per POSIX definition (optimal transfer block size, in bytes) - Change 'On Windows' to 'On some platforms' for statfs.type since libuv also returns 0 on Solaris, OpenBSD, NetBSD, Haiku, and QNX
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The documentation for the
fs.StatFsclass fields is minimal and lacks important details:statfs.bsizedoes not mention whether the value is in bits or bytes.statfs.bavail,statfs.bfree, andstatfs.blocksdo not explain how to use these values to calculate actual disk space.statfs.filesandstatfs.ffreedo not explain what "file nodes" (inodes) are or why they matter.statfs.typedoes not explain what the numeric value represents.Solution
fs.StatFsfield descriptions with proper units, context, and practical guidance.StatFsobject.bavailandbfree(reserved blocks for superuser).statfs.typeis a filesystem magic number and returns0on Windows.Why it matters
The
fs.StatFsclass is used for disk space monitoring and system health checks. Without clear documentation, users must guess at units, relationships between fields, or consult external sources. These improvements make the API self-documenting and reduce the learning curve for new users.Testing
This is a documentation-only change. The code examples have been manually verified for correctness.
Linked Issue
Refs: #50749