NAME¶

std::filesystem::space - std::filesystem::space

Synopsis¶

Defined in header <filesystem>
std::filesystem::space_info space(const std::filesystem::path& p);

std::filesystem::space_info space(const std::filesystem::path& p, (since C++17)

std::error_code& ec) noexcept;

Determines the information about the filesystem on which the pathname p is located,
as if by POSIX statvfs.

Populates and returns an object of type filesystem::space_info, set from the members
of the POSIX struct statvfs as follows

* space_info.capacity is set as if by f_blocks*f_frsize
* space_info.free is set to f_bfree*f_frsize
* space_info.available is set to f_bavail*f_frsize
* Any member that could not be determined is set to
static_cast<std::uintmax_t>(-1)

The non-throwing overload sets all members to static_cast<std::uintmax_t>(-1) on
error.

Parameters¶

p - path to examine
ec - out-parameter for error reporting in the non-throwing overload.

Return value¶

The filesystem information (a filesystem::space_info object).

Exceptions¶

The overload that does not take a std::error_code& parameter throws
filesystem::filesystem_error on underlying OS API errors, constructed with p as the
first path argument and the OS error code as the error code argument. The overload
taking a std::error_code& parameter sets it to the OS API error code if an OS API
call fails, and executes ec.clear() if no errors occur. Any overload not marked
noexcept may throw std::bad_alloc if memory allocation fails.

Notes¶

space_info.available may be less than space_info.free.

Example¶

// Run this code

#include <iostream>
#include <filesystem>
#include <cstdint>

void print_space_info(auto const& dirs, int width = 14)
{
std::cout << std::left;
for (const auto s : {"Capacity", "Free", "Available", "Dir"})
std::cout << "│ " << std::setw(width) << s << ' ';
std::cout << '\n';
std::error_code ec;
for (auto const& dir : dirs) {
const std::filesystem::space_info si = std::filesystem::space(dir, ec);
std::cout
<< "│ " << std::setw(width) << static_cast<std::intmax_t>(si.capacity) << ' '
<< "│ " << std::setw(width) << static_cast<std::intmax_t>(si.free) << ' '
<< "│ " << std::setw(width) << static_cast<std::intmax_t>(si.available) << ' '
<< "│ " << dir << '\n';
}
}

int main()
{
const auto dirs = { "/dev/null", "/tmp", "/home", "/null" };
print_space_info(dirs);
}

Possible output:¶

│ Capacity │ Free │ Available │ Dir
│ 8342851584 │ 8342851584 │ 8342851584 │ /dev/null
│ 12884901888 │ 3045265408 │ 3045265408 │ /tmp
│ 250321567744 │ 37623181312 │ 25152159744 │ /home
│ -1 │ -1 │ -1 │ /null

See also¶

space_info information about free and available space on the filesystem
(C++17) (class)