home | help 
std::filesystem::space(3)      C++ Standard Libary     std::filesystem::space(3)

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

Synopsis
	Defined in header <filesystem>
	std::filesystem::space_info  space(  const std::filesystem::path& p  (1)
     (since C++17)
	);
	std::filesystem::space_info space( const std::filesystem::path&  p,  (2)
     (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::uint-
     max_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
	Any  overload not marked noexcept may throw std::bad_alloc if memory al-
     location
	fails.

	1) Throws std::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.
	2)  Sets  a std::error_code& parameter to the OS API error code if an OS
     API call
	fails, and executes ec.clear() if no errors occur.

Notes
	space_info.available may be less than space_info.free.

Example
     // Run this code

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

      std::uintmax_t disk_usage_percent(const std::filesystem::space_info& si,
					bool is_privileged = false) noexcept
      {
	  if (constexpr std::uintmax_t X(-1);
	      si.capacity == 0 || si.free == 0 || si.available == 0 ||
	      si.capacity == X || si.free == X || si.available == X
	  )
	      return 100;

	  std::uintmax_t unused_space = si.free, capacity = si.capacity;
	  if (!is_privileged)
	  {
	      const std::uintmax_t privileged_only_space = si.free  -  si.avail-
     able;
	      unused_space -= privileged_only_space;
	      capacity -= privileged_only_space;
	  }
	  const std::uintmax_t used_space{capacity - unused_space};
	  return 100 * used_space / capacity;
      }

      void print_disk_space_info(auto const& dirs, int width = 14)
      {
	  (std::cout << std::left).imbue(std::locale("en_US.UTF-8"));

	  for (const auto s : {"Capacity", "Free", "Available", "Use%", "Dir"})
	      std::cout << "a " << std::setw(width) << s << ' ';

	  for (std::cout << '\n'; auto const& dir : dirs)
	  {
	      std::error_code ec;
	      const std::filesystem::space_info si = std::filesystem::space(dir,
     ec);
	      for (auto x : {si.capacity, si.free, si.available, disk_usage_per-
     cent(si)})
		  std::cout << "a " << std::setw(width) << static_cast<std::int-
     max_t>(x) << ' ';
	      std::cout << "a " << dir << '\n';
	  }
      }

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

Possible output:
      a Capacity       a Free		a Available	 a Use% 	  a Dir
      a  84,417,331,200  a  42,732,986,368  a  40,156,028,928 a 50	       a
     /dev/null
      a 84,417,331,200 a 42,732,986,368 a 40,156,028,928 a 50		  a /tmp
      a -1	       a -1		 a  -1		    a  100	       a
     /home
      a  0		 a  0		    a  0	      a 100	       a
     /proc
      a -1	       a -1		 a  -1		    a  100	       a
     /null

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

http://cppreference.com 	   2024.06.10	       std::filesystem::space(3)
home | help