DiskSpace (DiskSpace v1.0.0)

View Source

Provides disk space information by interfacing with a native NIF library.

The main function stat/2 returns disk space stats for a given filesystem path.

It also provides a bang variant stat!/2, which raises a DiskSpace.Error exception on error.

Both functions support optionally humanizing the output into strings (:humanize and :base options).

Summary

Functions

humanize(tagged_tuple, base_type \\ :binary)

Converts disk space statistics coming from stat/2 and stat!/2 from raw byte counts to human-readable strings.

stat(path, opts \\ [])

Retrieves disk space statistics for the given path.

stat!(path, opts \\ [])

Same as stat/2 (and with the same opts keyword-list options), but returns the stats_map plain Elixir map directly or raises DiskSpace.Error on failure.

Functions

humanize(tagged_tuple, base_type \\ :binary)

Converts disk space statistics coming from stat/2 and stat!/2 from raw byte counts to human-readable strings.

Accepts either a tuple {:ok, stats_map} (from stat/2) or a stats_map plain Elixir map (from a successful stat!/2), where the key values of stats_map are integer byte counts. Transparent for {:error, info} tuples returned from stat/2.

Returns the same structure but with all byte values converted to formatted human-readable strings (e.g., "10 GiB"), if the base_type argument value is non-nil and one of :binary (default) or :decimal.

Parameters

  • stats - either {:ok, stats_map} or a stats_map with keys like :available, :free, etc. and integer values representing bytes.
  • base_type - formatting base, either nil (do not do anything) or :binary (default, powers of 1024) or :decimal (powers of 1000). If non-nil, the atom determines the unit suffixes (KiB vs kB, etc.).

Examples

iex> DiskSpace.humanize({:ok, %{free: 123456789}}, nil)
{:ok, %{free: 123456789}}

iex> DiskSpace.humanize({:ok, %{free: 123456789}}, :binary)
{:ok, %{free: "117.74 MiB"}}

iex> DiskSpace.humanize(%{total: 1000000}, :decimal)
%{total: "1 MB"}

iex> DiskSpace.humanize({:error, :eio}, :binary)
{:error, :eio}

iex> DiskSpace.stat("/tmp") |> DiskSpace.humanize

stat(path, opts \\ [])

Retrieves disk space statistics for the given path.

Returns {:ok, stats_map} where stats_map is a plain Elixir map with the following keys and values in bytes:

  • :available - the number of bytes available to the current user. This excludes space reserved by the system or for privileged processes.

  • :free - the total number of free bytes on the filesystem, including space that may be reserved and unavailable to the current user.

  • :total - the total size of the filesystem in bytes.

  • :used - the number of bytes currently used (total - free).

Returns {:error, info} if the operation fails, where info is a map with keys :reason and :info; :reason is always an atom, :info provides more information or is nil, depending on what is reported by the NIF.

Options

  • :humanize (nil, :binary, or :decimal) - whether to convert byte counts into human-readable strings. Defaults to nil. If non-nil, the atom denotes the base used for human-readable formatting. See humanize/2.

stat!(path, opts \\ [])

Same as stat/2 (and with the same opts keyword-list options), but returns the stats_map plain Elixir map directly or raises DiskSpace.Error on failure.