fs: add statfs to fs

doc/api/fs.md

@@ -1001,6 +1001,82 @@ The times in the stat object have the following semantics:
 Prior to Node.js 0.12, the `ctime` held the `birthtime` on Windows systems. As
 of 0.12, `ctime` is not "creation time", and on Unix systems, it never was.
 
+## Class: `fs.StatFs`
+
+Provides information about a mounted filesystem.
+
+Objects returned from [`fs.statfs()`][] and its synchronous counterpart are of
+this type. If `bigint` in the `options` passed to those methods is `true`, the
+numeric values will be `bigint` instead of `number`.
+
+```console
+StatFs {
+ type: 1397114950,
+ bsize: 4096,
+ blocks: 121938943,
+ bfree: 61058895,
+ bavail: 61058895,
+ files: 999,
+ ffree: 1000000
+}
+```
+
+`bigint` version:
+
+```console
+StatFs {
+ type: 1397114950n,
+ bsize: 4096n,
+ blocks: 121938943n,
+ bfree: 61058895n,
+ bavail: 61058895n,
+ files: 999n,
+ ffree: 1000000n
+}
+```
+
+### `statfs.bavail`
+
+* {number|bigint}
+
+Free blocks available to unprivileged user.
+
+### `statfs.bfree`
+
+* {number|bigint}
+
+Free blocks in filesystem.
+
+### `statfs.blocks`
+
+* {number|bigint}
+
+Total data blocks in filesystem.
+
+### `statfs.bsize`
+
+* {number|bigint}
+
+Optimal transfer block size.
+
+### `statfs.ffree`
+
+* {number|bigint}
+
+Free file nodes in filesystem.
+
+### `statfs.files`
+
+* {number|bigint}
+
+Total file nodes in filesystem.
+
+### `statfs.type`
+
+* {number|bigint}
+
+Type of filesystem.
+
 ## Class: `fs.WriteStream`
 <!-- YAML
 added: v0.1.93
@@ -3465,6 +3541,39 @@ changes:
 
 Synchronous stat(2).
 
+## `fs.statfs(path[, options], callback)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string|Buffer|URL}
+* `options` {Object}
+ * `bigint` {boolean} Whether the numeric values in the returned
+ [`fs.StatFs`][] object should be `bigint`. **Default:** `false`.
+* `callback` {Function}
+ * `err` {Error}
+ * `stats` {fs.StatFs}
+
+Asynchronous statfs(2). The callback gets two arguments `(err, stats)` where
+`stats` is an [`fs.StatFs`][] object.
+
+Returns information about the mounted filesystem which contains `path`.
+
+In case of an error, the `err.code` will be one of [Common System Errors][].
+
+## `fs.statfsSync(path[, options])`
+<!-- YAML
+added: REPLACME
+-->
+
+* `path` {string|Buffer|URL}
+* `options` {Object}
+ * `bigint` {boolean} Whether the numeric values in the returned
+ [`fs.StatFs`][] object should be `bigint`. **Default:** `false`.
+* Returns: {fs.StatFs}
+
+Synchronous statfs(2).
+
 ## `fs.symlink(target, path[, type], callback)`
 <!-- YAML
 added: v0.1.31
@@ -5124,6 +5233,19 @@ changes:
 
 The `Promise` is resolved with the [`fs.Stats`][] object for the given `path`.
 
+### `fsPromises.statfs(path[, options])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string|Buffer|URL}
+* `options` {Object}
+ * `bigint` {boolean} Whether the numeric values in the returned
+ [`fs.StatFs`][] object should be `bigint`. **Default:** `false`.
+* Returns: {Promise}
+
+The `Promise` is resolved with the [`fs.StatFs`][] object for the given `path`.
+
 ### `fsPromises.symlink(target, path[, type])`
 <!-- YAML
 added: v10.0.0
@@ -5586,6 +5708,7 @@ the file contents.
 [`fs.Dirent`]: #fs_class_fs_dirent
 [`fs.FSWatcher`]: #fs_class_fs_fswatcher
 [`fs.Stats`]: #fs_class_fs_stats
+[`fs.StatFs`]: #fs_class_fs_statfs
 [`fs.access()`]: #fs_fs_access_path_mode_callback
 [`fs.chmod()`]: #fs_fs_chmod_path_mode_callback
 [`fs.chown()`]: #fs_fs_chown_path_uid_gid_callback
@@ -5609,6 +5732,7 @@ the file contents.
 [`fs.realpath()`]: #fs_fs_realpath_path_options_callback
 [`fs.rmdir()`]: #fs_fs_rmdir_path_options_callback
 [`fs.stat()`]: #fs_fs_stat_path_options_callback
+[`fs.statfs()`]: #fs_fs_statfs_path_options_callback
 [`fs.symlink()`]: #fs_fs_symlink_target_path_type_callback
 [`fs.utimes()`]: #fs_fs_utimes_path_atime_mtime_callback
 [`fs.watch()`]: #fs_fs_watch_filename_options_listener

lib/fs.js

@@ -76,6 +76,7 @@ const {
  Dirent,
  getDirents,
  getOptions,
+ getStatFsFromBinding,
  getValidatedPath,
  getValidMode,
  handleErrorFromBinding,
@@ -936,6 +937,24 @@ function stat(path, options = { bigint: false }, callback) {
  binding.stat(pathModule.toNamespacedPath(path), options.bigint, req);
 }
 
+function statfs(path, options = { bigint: false }, callback) {
+ if (typeof options === 'function') {
+ callback = options;
+ options = {};
+ }
+
+ callback = maybeCallback(callback);
+
+ const oncompleteCallback = (err, statsArray) => {
+ if (err) return callback(err);
+ callback(err, getStatFsFromBinding(statsArray));
+ };
+ path = getValidatedPath(path);
+ const req = new FSReqCallback(options.bigint);
+ req.oncomplete = oncompleteCallback;
+ binding.statfs(pathModule.toNamespacedPath(path), options.bigint, req);
+}
+
 function fstatSync(fd, options = { bigint: false }) {
  validateInt32(fd, 'fd', 0);
  const ctx = { fd };
@@ -962,6 +981,15 @@ function statSync(path, options = { bigint: false }) {
  return getStatsFromBinding(stats);
 }
 
+function statfsSync(path, options = { bigint: false }) {
+ path = getValidatedPath(path);
+ const ctx = { path };
+ const stats = binding.statfs(pathModule.toNamespacedPath(path),
+ options.bigint, undefined, ctx);
+ handleErrorFromBinding(ctx);
+ return getStatFsFromBinding(stats);
+}
+
 function readlink(path, options, callback) {
  callback = makeCallback(typeof options === 'function' ? options : callback);
  options = getOptions(options, {});
@@ -1920,7 +1948,9 @@ module.exports = fs = {
  rmdir,
  rmdirSync,
  stat,
+ statfs,
  statSync,
+ statfsSync,
  symlink,
  symlinkSync,
  truncate,

lib/internal/fs/promises.js

@@ -33,6 +33,7 @@ const {
  getDirents,
  getOptions,
  getStatsFromBinding,
+ getStatFsFromBinding,
  getValidatedPath,
  getValidMode,
  nullCheck,
@@ -405,6 +406,13 @@ async function stat(path, options = { bigint: false }) {
  return getStatsFromBinding(result);
 }
 
+async function statfs(path, options = { bigint: false }) {
+ path = getValidatedPath(path);
+ const result = await binding.statfs(pathModule.toNamespacedPath(path),
+ options.bigint, kUsePromises);
+ return getStatFsFromBinding(result);
+}
+
 async function link(existingPath, newPath) {
  existingPath = getValidatedPath(existingPath, 'existingPath');
  newPath = getValidatedPath(newPath, 'newPath');
@@ -536,6 +544,7 @@ module.exports = {
  symlink,
  lstat,
  stat,
+ statfs,
  link,
  unlink,
  chmod,

lib/internal/fs/utils.js

@@ -458,6 +458,24 @@ function getStatsFromBinding(stats, offset = 0) {
  );
 }
 
+function StatFs(type, bsize, blocks, bfree,
+ bavail, files, ffree) {
+ this.type = type;
+ this.bsize = bsize;
+ this.blocks = blocks;
+ this.bfree = bfree;
+ this.bavail = bavail;
+ this.files = files;
+ this.ffree = ffree;
+}
+
+function getStatFsFromBinding(stats) {
+ return new StatFs(
+ stats[0], stats[1], stats[2], stats[3],
+ stats[4], stats[5], stats[6]
+ );
+}
+
 function stringToFlags(flags) {
  if (typeof flags === 'number') {
  return flags;
@@ -669,6 +687,7 @@ module.exports = {
  getDirent,
  getDirents,
  getOptions,
+ getStatFsFromBinding,
  getValidatedPath,
  getValidMode,
  handleErrorFromBinding,

src/env-inl.h

@@ -615,6 +615,14 @@ inline AliasedBigUint64Array* Environment::fs_stats_field_bigint_array() {
  return &fs_stats_field_bigint_array_;
 }
 
+inline AliasedFloat64Array* Environment::fs_statfs_field_array() {
+ return &fs_statfs_field_array_;
+}
+
+inline AliasedBigUint64Array* Environment::fs_statfs_field_bigint_array() {
+ return &fs_statfs_field_bigint_array_;
+}
+
 inline std::vector<std::unique_ptr<fs::FileHandleReadWrap>>&
 Environment::file_handle_read_wrap_freelist() {
  return file_handle_read_wrap_freelist_;

src/env.cc

@@ -309,6 +309,8 @@ Environment::Environment(IsolateData* isolate_data,
  thread_id_(thread_id == kNoThreadId ? AllocateThreadId() : thread_id),
  fs_stats_field_array_(isolate_, kFsStatsBufferLength),
  fs_stats_field_bigint_array_(isolate_, kFsStatsBufferLength),
+ fs_statfs_field_array_(isolate_, kFsStatfsBufferLength),
+ fs_statfs_field_bigint_array_(isolate_, kFsStatfsBufferLength),
  context_(context->GetIsolate(), context) {
  // We'll be creating new objects so make sure we've entered the context.
  HandleScope handle_scope(isolate());
@@ -1068,6 +1070,9 @@ void Environment::MemoryInfo(MemoryTracker* tracker) const {
  tracker->TrackField("fs_stats_field_array", fs_stats_field_array_);
  tracker->TrackField("fs_stats_field_bigint_array",
  fs_stats_field_bigint_array_);
+ tracker->TrackField("fs_statfs_field_array", fs_statfs_field_array_);
+ tracker->TrackField("fs_statfs_field_bigint_array",
+ fs_statfs_field_bigint_array_);
  tracker->TrackField("cleanup_hooks", cleanup_hooks_);
  tracker->TrackField("async_hooks", async_hooks_);
  tracker->TrackField("immediate_info", immediate_info_);

src/env.h

@@ -135,6 +135,20 @@ enum class FsStatsOffset {
 constexpr size_t kFsStatsBufferLength =
  static_cast<size_t>(FsStatsOffset::kFsStatsFieldsNumber) * 2;
 
+enum class FsStatfsOffset {
+ kType = 0,
+ kBSize,
+ kBlocks,
+ kBFree,
+ kBAvail,
+ kFiles,
+ kFFree,
+ kFsStatFsFieldsNumber
+};
+
+constexpr size_t kFsStatfsBufferLength =
+ static_cast<size_t>(FsStatfsOffset::kFsStatFsFieldsNumber);
+
 // PER_ISOLATE_* macros: We have a lot of per-isolate properties
 // and adding and maintaining their getters and setters by hand would be
 // difficult so let's make the preprocessor generate them for us.
@@ -1025,6 +1039,9 @@ class Environment : public MemoryRetainer {
  inline AliasedFloat64Array* fs_stats_field_array();
  inline AliasedBigUint64Array* fs_stats_field_bigint_array();
 
+ inline AliasedFloat64Array* fs_statfs_field_array();
+ inline AliasedBigUint64Array* fs_statfs_field_bigint_array();
+
  inline std::vector<std::unique_ptr<fs::FileHandleReadWrap>>&
  file_handle_read_wrap_freelist();
 
@@ -1386,6 +1403,9 @@ class Environment : public MemoryRetainer {
  AliasedFloat64Array fs_stats_field_array_;
  AliasedBigUint64Array fs_stats_field_bigint_array_;
 
+ AliasedFloat64Array fs_statfs_field_array_;
+ AliasedBigUint64Array fs_statfs_field_bigint_array_;
+
  std::vector<std::unique_ptr<fs::FileHandleReadWrap>>
  file_handle_read_wrap_freelist_;