Reference

std/os/volumes

std/os/src/volumes.trb

Volume - a mounted file system - with its VolumeKind and, in step with Volume.space, its VolumeSpace.

Volume.all is a match OperatingSystem.current whose arm hands the question to the directory of that system; only the arm of the build's target is compiled.

type Volume

type Volume with Show, Equals

A mounted file system: where it is mounted, what is mounted there, and what kind of storage it is.

Examples

for volume in Volume.all()? {
  print "{volume.mountPoint} {volume.fileSystem} {volume.kind}"
}

Pitfalls

  • A volume mounted in two places is two values, one per mount point, on every system.
  • device is a name in the system's own namespace (/dev/nvme0n1p2, tmpfs, server:/export, a volume GUID path on Windows) and no Path operation means anything on it.

Related

field mountPoint

mountPoint: Path

Where it is mounted: C:/, /, /home, /Volumes/Backup.

field device

device: String

What is mounted: \\?\Volume{…}\, /dev/nvme0n1p2, tmpfs, server:/export.

field fileSystem

fileSystem: String

As the system names it: NTFS, ext4, apfs, tmpfs, nfs4.

field label

label: String?

The name the user gave it, where the system knows one.

field kind

kind: VolumeKind

What storage it is: fixed, removable, network, optical, memory or virtual.

field readOnly

readOnly: Bool

Whether nothing can be written to it.

fn isRemovable

fn isRemovable(): Bool

Whether it can be taken out of the machine: a USB stick, a memory card.

fn all

static fn all(includeVirtual: Bool = false): Result<List<Volume>, OsError>

The mounted file systems, from the mount table. It never waits, because it asks no file system anything. The virtual ones - proc, sysfs, devfs - are left out unless includeVirtual asks for them.

Errors

  • OsError.Malformed where a line of /proc/self/mountinfo is not in the form Linux writes it.
  • OsError.Unsupported on FreeBSD, whose slice has not come yet, and in a browser, which has no file systems.
  • OsError.Failed where the system's call fails, with its words.

Examples

const volumes = Volume.all()?
print "{volumes.length()} volumes"

fn space

fn space(): Task<Result<VolumeSpace, OsError>>

How big it is and how much of it is free. This asks the file system itself, which can take a moment for a network one, and is why it is a task.

Errors

  • OsError.Missing where the volume has gone since it was listed, OsError.Denied where it may not be read.
  • OsError.Unsupported on FreeBSD, whose slice has not come yet, and in a browser.

Examples

for volume in Volume.all()? {
  const space = volume.space().await()?
  print "{volume.mountPoint} {space.used().gigabytes()} GB used"
}

fn containing

static fn containing(path: Path): Task<Result<Volume, OsError>>

The volume that holds path: the mount point that is the longest prefix of it. A relative path is resolved against the working directory, and .. and . are folded away; a link is not followed, so a link into another volume belongs to the volume of the link. The virtual volumes are candidates too, so /proc/self belongs to proc.

Errors

  • OsError.Missing where path does not exist.
  • OsError.Denied where the file system may not be asked about it.
  • OsError.Unsupported on FreeBSD and in a browser.

Examples

const volume = Volume.containing(Path.from("/home/ada/notes.txt")).await()?
print "{volume.mountPoint} is {volume.fileSystem}"

fn isVirtual

fn isVirtual(): Bool

Whether it is a view of the kernel rather than storage.

type VolumeKind

type VolumeKind with Show, Equals

What a Volume is stored on.

case Fixed

case Fixed

A disk built into the machine.

case Removable

case Removable

A USB stick, a memory card, any disk the system says can be taken out.

case Network

case Network

Served by another machine: nfs4, cifs, a Windows network drive.

case Optical

case Optical

A CD, DVD or Blu-ray.

case Memory

case Memory

Backed by memory: tmpfs, a RAM disk.

case Virtual

case Virtual

A view of the kernel rather than storage: proc, sysfs, devfs. Left out of Volume.all unless asked for.

case Unknown

case Unknown

The system does not say.

type VolumeSpace

type VolumeSpace with Show, Equals

How big a Volume is and how much of it is free. available <= free <= total.

Related

  • Volume - which it belongs to.

field total

total: ByteSize

The size of the volume.

field free

free: ByteSize

What the system holds free.

field available

available: ByteSize

What this user may still write: less than free where the system reserves blocks for its administrator.

fn used

fn used(): ByteSize

What is taken: total - free.