From 07500241baadb17bf9ab1b4f802c6873a9373fd1 Mon Sep 17 00:00:00 2001
From: shrenisc <shreya.shastry@gmail.com>
Date: Sat, 5 Oct 2024 17:44:38 +0530
Subject: [PATCH 1/7] doc: updated the Class:fs filesystem documentation as it
 was missing information and examples

Defined the return type for statfs.bsize. Added examples for statfs.bavail, statfs.bfree, statfs.blocks and statfs.files for clarity. Cleared the air on why statfs.type returns a int|bigint value.

Fixes: https://github.com/nodejs/node/issues/50749
---
 doc/api/fs.md | 167 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 166 insertions(+), 1 deletion(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 374e51434d78a2..f86292a7bf3cf3 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7510,6 +7510,24 @@ added:
 
 Free blocks available to unprivileged users.
 
+Example:
+```mjs
+const fs = require('fs');
+
+// Specify the path you want to check (like '/' or 'C:/').
+fs.statfs('.', (err, stats) => {
+  if (err) {
+    console.error('Error reading file system stats:', err);
+    return;
+  }
+
+  // Calculate available space in bytes
+  const availableSpace = stats.bavail * stats.bsize;
+
+  console.log(`Available space for unprivileged users: ${availableSpace} bytes`);
+});
+```
+
 #### `statfs.bfree`
 
 <!-- YAML
@@ -7522,6 +7540,24 @@ added:
 
 Free blocks in file system.
 
+Example:
+```mjs
+const fs = require('fs');
+
+// Specify the path of the filesystem to check (e.g., current directory).
+fs.statfs('.', (err, stats) => {
+  if (err) {
+    console.error('Error reading file system stats:', err);
+    return;
+  }
+
+  // Calculate total free space in bytes using bfree and bsize
+  const totalFreeSpace = stats.bfree * stats.bsize;
+
+  console.log(`Total free space (including reserved blocks): ${totalFreeSpace} bytes`);
+});
+```
+
 #### `statfs.blocks`
 
 <!-- YAML
@@ -7534,6 +7570,24 @@ added:
 
 Total data blocks in file system.
 
+Example:
+```mjs
+const fs = require('fs');
+
+// Specify the path of the filesystem to check (e.g., current directory).
+fs.statfs('.', (err, stats) => {
+  if (err) {
+    console.error('Error reading file system stats:', err);
+    return;
+  }
+
+  // Get the total number of blocks
+  const totalBlocks = stats.blocks;
+
+  console.log(`Total number of blocks on the filesystem: ${totalBlocks}`);
+});
+```
+
 #### `statfs.bsize`
 
 <!-- YAML
@@ -7544,7 +7598,7 @@ added:
 
 * {number|bigint}
 
-Optimal transfer block size.
+Optimal transfer block size(this value is in bytes for POSIX-compliant or UNIX-like Operating Systems including but not limited to Windows, Linux, MacOS, FreeBSD, OpenBSD, NetBSD, Solaris/Illumos etc).
 
 #### `statfs.ffree`
 
@@ -7570,6 +7624,24 @@ added:
 
 Total file nodes in file system.
 
+Example:
+```mjs
+const fs = require('fs');
+
+// Specify the path of the filesystem to check (e.g., current directory).
+fs.statfs('.', (err, stats) => {
+  if (err) {
+    console.error('Error reading file system stats:', err);
+    return;
+  }
+
+  // Calculate total free space in bytes using bfree and bsize
+  const totalFreeSpace = stats.bfree * stats.bsize;
+
+  console.log(`Total free space (including reserved blocks): ${totalFreeSpace} bytes`);
+});
+```
+
 #### `statfs.type`
 
 <!-- YAML
@@ -7581,6 +7653,99 @@ added:
 * {number|bigint}
 
 Type of file system.
+This value is the decimal representation of the magic number* of the filesystem. Converting this number|bigint to hexadecimal will return the magic number.
+
+*magic number- refers to the hexadecimal numeric coding mapped to each filesystem.
+
+Here are some common filesystems and their magic numbers:
+<table>
+  <tr>
+    <th>Filesystem</th>
+    <th>Magic Number (Hexadecimal)</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>ext2</td>
+    <td>0xEF53</td>
+    <td>Second Extended File System (Linux)</td>
+  </tr>
+  <tr>
+    <td>ext3</td>
+    <td>0xEF53</td>
+    <td>Third Extended File System (Linux)</td>
+  </tr>
+  <tr>
+    <td>ext4</td>
+    <td>0xEF53</td>
+    <td>Fourth Extended File System (Linux)</td>
+  </tr>
+  <tr>
+    <td>Btrfs</td>
+    <td>0x9123683E</td>
+    <td>B-tree File System (Linux)</td>
+  </tr>
+  <tr>
+    <td>XFS</td>
+    <td>0x58465342</td>
+    <td>X File System (Linux)</td>
+  </tr>
+  <tr>
+    <td>FAT</td>
+    <td>0xadf5</td>
+    <td>File Allocation Table (legacy FAT)</td>
+  </tr>
+  <tr>
+    <td>NFS</td>
+    <td>0x6969</td>
+    <td>Network File System</td>
+  </tr>
+  <tr>
+    <td>ISO 9660</td>
+    <td>0x9660</td>
+    <td>CD-ROM File System</td>
+  </tr>
+  <tr>
+    <td>SMB/CIFS</td>
+    <td>0xFF534D42</td>
+    <td>Server Message Block / Common Internet File System</td>
+  </tr>
+  <tr>
+    <td>JFFS2</td>
+    <td>0x72B6</td>
+    <td>Journaling Flash File System</td>
+  </tr>
+  <tr>
+    <td>UDF</td>
+    <td>0x15013346</td>
+    <td>Universal Disk Format</td>
+  </tr>
+  <tr>
+    <td>procfs</td>
+    <td>0x9fa0</td>
+    <td>Process File System</td>
+  </tr>
+  <tr>
+    <td>sysfs</td>
+    <td>0x62656572</td>
+    <td>System File System</td>
+  </tr>
+  <tr>
+    <td>tmpfs</td>
+    <td>0x01021994</td>
+    <td>Temporary File System</td>
+  </tr>
+  <tr>
+    <td>cgroupfs</td>
+    <td>0x27e0eb</td>
+    <td>Control Group File System</td>
+  </tr>
+  <tr>
+    <td>ramfs</td>
+    <td>0x858458f6</td>
+    <td>RAM File System</td>
+  </tr>
+</table>
+
 
 ### Class: `fs.WriteStream`
 

From dd678e4cb2d34f9b662b79b956bbc01bf28d4745 Mon Sep 17 00:00:00 2001
From: Shreya Shastry <91794581+shrenisc@users.noreply.github.com>
Date: Sat, 5 Oct 2024 23:04:08 +0530
Subject: [PATCH 2/7] Update doc/api/fs.md

Co-authored-by: Aviv Keller <redyetidev@gmail.com>
---
 doc/api/fs.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index f86292a7bf3cf3..e84db8f4082881 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7598,7 +7598,7 @@ added:
 
 * {number|bigint}
 
-Optimal transfer block size(this value is in bytes for POSIX-compliant or UNIX-like Operating Systems including but not limited to Windows, Linux, MacOS, FreeBSD, OpenBSD, NetBSD, Solaris/Illumos etc).
+Optimal transfer block size (measured in bytes)
 
 #### `statfs.ffree`
 

From e9a872b666f1c2b491291aa0bf35f1d8e345edcc Mon Sep 17 00:00:00 2001
From: Shreya Shastry <91794581+shrenisc@users.noreply.github.com>
Date: Sat, 5 Oct 2024 23:21:11 +0530
Subject: [PATCH 3/7] Update doc/api/fs.md

Co-authored-by: Aviv Keller <redyetidev@gmail.com>
---
 doc/api/fs.md | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index e84db8f4082881..011b46459c7bf4 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7652,10 +7652,7 @@ added:
 
 * {number|bigint}
 
-Type of file system.
-This value is the decimal representation of the magic number* of the filesystem. Converting this number|bigint to hexadecimal will return the magic number.
-
-*magic number- refers to the hexadecimal numeric coding mapped to each filesystem.
+Type of file system, represented by the decimal form of the file's magic number.
 
 Here are some common filesystems and their magic numbers:
 <table>

From 78ee107d8a631351fad7ed4278c0b68262f32b37 Mon Sep 17 00:00:00 2001
From: shrenisc <shreya.shastry@gmail.com>
Date: Sat, 5 Oct 2024 17:44:38 +0530
Subject: [PATCH 4/7] doc: updated the Class:fs filesystem documentation as it
 was missing information and examples

Defined the return type for statfs.bsize. Added examples for statfs.bavail, statfs.bfree, statfs.blocks and statfs.files for clarity. Cleared the air on why statfs.type returns a int|bigint value.

Fixes: https://github.com/nodejs/node/issues/50749
---
 doc/api/fs.md | 167 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 166 insertions(+), 1 deletion(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 374e51434d78a2..f86292a7bf3cf3 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7510,6 +7510,24 @@ added:
 
 Free blocks available to unprivileged users.
 
+Example:
+```mjs
+const fs = require('fs');
+
+// Specify the path you want to check (like '/' or 'C:/').
+fs.statfs('.', (err, stats) => {
+  if (err) {
+    console.error('Error reading file system stats:', err);
+    return;
+  }
+
+  // Calculate available space in bytes
+  const availableSpace = stats.bavail * stats.bsize;
+
+  console.log(`Available space for unprivileged users: ${availableSpace} bytes`);
+});
+```
+
 #### `statfs.bfree`
 
 <!-- YAML
@@ -7522,6 +7540,24 @@ added:
 
 Free blocks in file system.
 
+Example:
+```mjs
+const fs = require('fs');
+
+// Specify the path of the filesystem to check (e.g., current directory).
+fs.statfs('.', (err, stats) => {
+  if (err) {
+    console.error('Error reading file system stats:', err);
+    return;
+  }
+
+  // Calculate total free space in bytes using bfree and bsize
+  const totalFreeSpace = stats.bfree * stats.bsize;
+
+  console.log(`Total free space (including reserved blocks): ${totalFreeSpace} bytes`);
+});
+```
+
 #### `statfs.blocks`
 
 <!-- YAML
@@ -7534,6 +7570,24 @@ added:
 
 Total data blocks in file system.
 
+Example:
+```mjs
+const fs = require('fs');
+
+// Specify the path of the filesystem to check (e.g., current directory).
+fs.statfs('.', (err, stats) => {
+  if (err) {
+    console.error('Error reading file system stats:', err);
+    return;
+  }
+
+  // Get the total number of blocks
+  const totalBlocks = stats.blocks;
+
+  console.log(`Total number of blocks on the filesystem: ${totalBlocks}`);
+});
+```
+
 #### `statfs.bsize`
 
 <!-- YAML
@@ -7544,7 +7598,7 @@ added:
 
 * {number|bigint}
 
-Optimal transfer block size.
+Optimal transfer block size(this value is in bytes for POSIX-compliant or UNIX-like Operating Systems including but not limited to Windows, Linux, MacOS, FreeBSD, OpenBSD, NetBSD, Solaris/Illumos etc).
 
 #### `statfs.ffree`
 
@@ -7570,6 +7624,24 @@ added:
 
 Total file nodes in file system.
 
+Example:
+```mjs
+const fs = require('fs');
+
+// Specify the path of the filesystem to check (e.g., current directory).
+fs.statfs('.', (err, stats) => {
+  if (err) {
+    console.error('Error reading file system stats:', err);
+    return;
+  }
+
+  // Calculate total free space in bytes using bfree and bsize
+  const totalFreeSpace = stats.bfree * stats.bsize;
+
+  console.log(`Total free space (including reserved blocks): ${totalFreeSpace} bytes`);
+});
+```
+
 #### `statfs.type`
 
 <!-- YAML
@@ -7581,6 +7653,99 @@ added:
 * {number|bigint}
 
 Type of file system.
+This value is the decimal representation of the magic number* of the filesystem. Converting this number|bigint to hexadecimal will return the magic number.
+
+*magic number- refers to the hexadecimal numeric coding mapped to each filesystem.
+
+Here are some common filesystems and their magic numbers:
+<table>
+  <tr>
+    <th>Filesystem</th>
+    <th>Magic Number (Hexadecimal)</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>ext2</td>
+    <td>0xEF53</td>
+    <td>Second Extended File System (Linux)</td>
+  </tr>
+  <tr>
+    <td>ext3</td>
+    <td>0xEF53</td>
+    <td>Third Extended File System (Linux)</td>
+  </tr>
+  <tr>
+    <td>ext4</td>
+    <td>0xEF53</td>
+    <td>Fourth Extended File System (Linux)</td>
+  </tr>
+  <tr>
+    <td>Btrfs</td>
+    <td>0x9123683E</td>
+    <td>B-tree File System (Linux)</td>
+  </tr>
+  <tr>
+    <td>XFS</td>
+    <td>0x58465342</td>
+    <td>X File System (Linux)</td>
+  </tr>
+  <tr>
+    <td>FAT</td>
+    <td>0xadf5</td>
+    <td>File Allocation Table (legacy FAT)</td>
+  </tr>
+  <tr>
+    <td>NFS</td>
+    <td>0x6969</td>
+    <td>Network File System</td>
+  </tr>
+  <tr>
+    <td>ISO 9660</td>
+    <td>0x9660</td>
+    <td>CD-ROM File System</td>
+  </tr>
+  <tr>
+    <td>SMB/CIFS</td>
+    <td>0xFF534D42</td>
+    <td>Server Message Block / Common Internet File System</td>
+  </tr>
+  <tr>
+    <td>JFFS2</td>
+    <td>0x72B6</td>
+    <td>Journaling Flash File System</td>
+  </tr>
+  <tr>
+    <td>UDF</td>
+    <td>0x15013346</td>
+    <td>Universal Disk Format</td>
+  </tr>
+  <tr>
+    <td>procfs</td>
+    <td>0x9fa0</td>
+    <td>Process File System</td>
+  </tr>
+  <tr>
+    <td>sysfs</td>
+    <td>0x62656572</td>
+    <td>System File System</td>
+  </tr>
+  <tr>
+    <td>tmpfs</td>
+    <td>0x01021994</td>
+    <td>Temporary File System</td>
+  </tr>
+  <tr>
+    <td>cgroupfs</td>
+    <td>0x27e0eb</td>
+    <td>Control Group File System</td>
+  </tr>
+  <tr>
+    <td>ramfs</td>
+    <td>0x858458f6</td>
+    <td>RAM File System</td>
+  </tr>
+</table>
+
 
 ### Class: `fs.WriteStream`
 

From 8b9abe6d5e3d720e449adec1d3aad7864f14bb85 Mon Sep 17 00:00:00 2001
From: shrenisc <shreya.shastry@gmail.com>
Date: Sun, 6 Oct 2024 00:01:52 +0530
Subject: [PATCH 5/7] doc: add missing examples and information to fs

Defined the return type for statfs.bsize. Added examples for statfs.bavail, statfs.bfree, statfs.blocks and statfs.files for clarity. Explained why statfs.type returns a int|bigint value and added a table with most commonly used filesystems and their magic numbers.

Fixes: #50749
---
 doc/api/fs.md | 62 ++++-----------------------------------------------
 1 file changed, 4 insertions(+), 58 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index a6e9bec59d4b6a..987873b92add48 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7511,34 +7511,7 @@ added:
 Free blocks available to unprivileged users.
 
 Example:
-```mjs
-const fs = require('fs');
-
-// Specify the path you want to check (like '/' or 'C:/').
-fs.statfs('.', (err, stats) => {
-  if (err) {
-    console.error('Error reading file system stats:', err);
-    return;
-  }
-
-  // Calculate available space in bytes
-  const availableSpace = stats.bavail * stats.bsize;
-
-  console.log(`Available space for unprivileged users: ${availableSpace} bytes`);
-});
-```
-
-Example:
-```mjs
-const fs = require('fs');
-
-// Specify the path you want to check (like '/' or 'C:/').
-fs.statfs('.', (err, stats) => {
-  if (err) {
-    console.error('Error reading file system stats:', err);
-    return;
-  }
-
+```js
   // Calculate available space in bytes
   const availableSpace = stats.bavail * stats.bsize;
 
@@ -7559,16 +7532,7 @@ added:
 Free blocks in file system.
 
 Example:
-```mjs
-const fs = require('fs');
-
-// Specify the path of the filesystem to check (e.g., current directory).
-fs.statfs('.', (err, stats) => {
-  if (err) {
-    console.error('Error reading file system stats:', err);
-    return;
-  }
-
+```js
   // Calculate total free space in bytes using bfree and bsize
   const totalFreeSpace = stats.bfree * stats.bsize;
 
@@ -7589,16 +7553,7 @@ added:
 Total data blocks in file system.
 
 Example:
-```mjs
-const fs = require('fs');
-
-// Specify the path of the filesystem to check (e.g., current directory).
-fs.statfs('.', (err, stats) => {
-  if (err) {
-    console.error('Error reading file system stats:', err);
-    return;
-  }
-
+```js
   // Get the total number of blocks
   const totalBlocks = stats.blocks;
 
@@ -7643,16 +7598,7 @@ added:
 Total file nodes in file system.
 
 Example:
-```mjs
-const fs = require('fs');
-
-// Specify the path of the filesystem to check (e.g., current directory).
-fs.statfs('.', (err, stats) => {
-  if (err) {
-    console.error('Error reading file system stats:', err);
-    return;
-  }
-
+```js
   // Calculate total free space in bytes using bfree and bsize
   const totalFreeSpace = stats.bfree * stats.bsize;
 

From 1e201502f9856ab3fcae1bc81f7eaf0c37ac41a6 Mon Sep 17 00:00:00 2001
From: shrenisc <shreya.shastry@gmail.com>
Date: Sun, 6 Oct 2024 00:23:06 +0530
Subject: [PATCH 6/7] doc: add missing examples and information to fs

Defined the return type for statfs.bsize. Added examples for statfs.bavail, statfs.bfree, statfs.blocks and statfs.files for clarity. Explained why statfs.type returns a int|bigint value and added a table with most commonly used magic numbers and their filesystems.

Fixes: #50749
---
 doc/api/fs.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 987873b92add48..aabc37a5befb70 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7512,7 +7512,9 @@ Free blocks available to unprivileged users.
 
 Example:
 ```js
+  const fs = require('fs');
   // Calculate available space in bytes
+  fs.statfs('.', (err,stats) => {
   const availableSpace = stats.bavail * stats.bsize;
 
   console.log(`Available space for unprivileged users: ${availableSpace} bytes`);
@@ -7533,7 +7535,9 @@ Free blocks in file system.
 
 Example:
 ```js
+  const fs = require('fs');
   // Calculate total free space in bytes using bfree and bsize
+  fs.statfs('.', (err,stats) => {
   const totalFreeSpace = stats.bfree * stats.bsize;
 
   console.log(`Total free space (including reserved blocks): ${totalFreeSpace} bytes`);
@@ -7554,7 +7558,9 @@ Total data blocks in file system.
 
 Example:
 ```js
+  const fs = require('fs');
   // Get the total number of blocks
+  fs.statfs('.', (err,stats) => {
   const totalBlocks = stats.blocks;
 
   console.log(`Total number of blocks on the filesystem: ${totalBlocks}`);
@@ -7599,6 +7605,8 @@ Total file nodes in file system.
 
 Example:
 ```js
+  const fs = require('fs');
+  fs.statfs('.', (err, stats) => {
   // Calculate total free space in bytes using bfree and bsize
   const totalFreeSpace = stats.bfree * stats.bsize;
 

From d4f5ce13ab8d36174c4866e3819ffe989528f773 Mon Sep 17 00:00:00 2001
From: Shreya Shastry <91794581+shrenisc@users.noreply.github.com>
Date: Sun, 6 Oct 2024 00:24:55 +0530
Subject: [PATCH 7/7] doc: add missing examples and information to fs

Co-authored-by: Aviv Keller <redyetidev@gmail.com>
---
 doc/api/fs.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index aabc37a5befb70..dfc25e908f5207 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7577,7 +7577,7 @@ added:
 
 * {number|bigint}
 
-Optimal transfer block size (measured in bytes)
+Optimal transfer block size (measured in bytes).
 
 #### `statfs.ffree`