fs: add statvfs function

Expose useful functionality to query filesystem properties,
such as free size, total size, and various other block
properties made available via
https://www.man7.org/linux/man-pages/man3/statvfs.3.html

If the host runs Linux, we also expose the `type` property,
which provides the FS type magic number.

Complete jsdoc is provided for the new object and function.

Run-tested on macOS and OpenWRT 25.12-rc5

Signed-off-by: Paul Donald <newtwen+github@gmail.com>

Author: systemcrash

lib/fs.c

@@ -60,8 +60,10 @@
 #include <fnmatch.h>
 #include <limits.h>
 #include <fcntl.h>
+#include <sys/statvfs.h>  /* statvfs(3) */
 
 #if defined(__linux__)
+#include <sys/statfs.h>   /* statfs() for f_type */
 #define HAS_IOCTL
 #endif
 
@@ -1779,6 +1781,89 @@ uc_fs_lstat(uc_vm_t *vm, size_t nargs)
 	return uc_fs_stat_common(vm, nargs, true);
 }
 
+/**
+ * @typedef {Object} module:fs.StatVFSResult
+ * @property {number} bsize file system block size
+ * @property {number} frsize fragment size
+ * @property {number} blocks total blocks
+ * @property {number} bfree free blocks
+ * @property {number} bavail free blocks available to unprivileged users
+ * @property {number} files total file nodes (inodes)
+ * @property {number} ffree free file nodes
+ * @property {number} favail free nodes available to unprivileged users
+ * @property {number} fsid file system id
+ * @property {number} flag mount flags
+ * @property {number} namemax maximum filename length
+ * @property {number} freesize free space in bytes (calculated as `frsize * bfree`)
+ * @property {number} totalsize total size of the filesystem (calculated as `frsize * blocks`)
+ * @property {number} type (Linux only) magic number of the filesystem, obtained from `statfs`
+ */
+
+/**
+ * Query filesystem statistics for a given pathname.
+ *
+ * The returned object mirrors the members of `struct statvfs`.
+ * Convenience properties `freesize` and `totalsize` are added,
+ * which are calculated as:
+ * - `frsize * bfree` to provide the free space in bytes and
+ * - `frsize * blocks` to provide the total size of the filesystem.
+ *
+ * On Linux an additional `type` field (magic number from `statfs`) is
+ * provided if the call succeeds.
+ *
+ * Returns `null` on failure (and sets `fs.last_error`).
+ *
+ * @function module:fs#statvfs
+ *
+ * @param {string} path
+ * The path to the directory or file with which to query the filesystem.
+ *
+ * @returns {?module:fs.StatVFSResult}
+ *
+ * @example
+ * // Get filesystem statistics for a path
+ * const stats = statvfs('path/to/directory');
+ * print(stats.bsize); // file system block size
+ */
+static uc_value_t *
+uc_fs_statvfs(uc_vm_t *vm, size_t nargs)
+{
+	uc_value_t *path = uc_fn_arg(0);
+	struct statvfs sv;
+
+	if (ucv_type(path) != UC_STRING)
+		err_return(EINVAL);
+
+	if (statvfs(ucv_string_get(path), &sv) == -1)
+		err_return(errno);
+
+	uc_value_t *o = ucv_object_new(vm);
+
+	ucv_object_add(o, "bsize",    ucv_int64_new(sv.f_bsize));
+	ucv_object_add(o, "frsize",   ucv_int64_new(sv.f_frsize));
+	ucv_object_add(o, "blocks",   ucv_int64_new(sv.f_blocks));
+	ucv_object_add(o, "bfree",    ucv_int64_new(sv.f_bfree));
+	ucv_object_add(o, "bavail",   ucv_int64_new(sv.f_bavail));
+	ucv_object_add(o, "files",    ucv_int64_new(sv.f_files));
+	ucv_object_add(o, "ffree",    ucv_int64_new(sv.f_ffree));
+	ucv_object_add(o, "favail",   ucv_int64_new(sv.f_favail));
+	ucv_object_add(o, "fsid",     ucv_int64_new(sv.f_fsid));
+	ucv_object_add(o, "flag",     ucv_int64_new(sv.f_flag));
+	ucv_object_add(o, "namemax",  ucv_int64_new(sv.f_namemax));
+	ucv_object_add(o, "freesize", ucv_int64_new(sv.f_frsize * sv.f_bfree));
+	ucv_object_add(o, "totalsize",ucv_int64_new(sv.f_frsize * sv.f_blocks));
+
+#ifdef __linux__
+	/* Call statfs to expose the magic number (`f_type`) */
+	struct statfs sf;
+	if (statfs(ucv_string_get(path), &sf) == 0) {
+		ucv_object_add(o, "type", ucv_int64_new(sf.f_type));
+	}
+#endif
+
+	return o;
+}
+
 /**
  * Creates a new directory.
  *
@@ -3024,6 +3109,7 @@ static const uc_function_list_t global_fns[] = {
 	{ "popen",		uc_fs_popen },
 	{ "readlink",	uc_fs_readlink },
 	{ "stat",		uc_fs_stat },
+    { "statvfs",    uc_fs_statvfs },
 	{ "lstat",		uc_fs_lstat },
 	{ "mkdir",		uc_fs_mkdir },
 	{ "rmdir",		uc_fs_rmdir },