@photostructure/fs-metadata
    Preparing search index...

    Interface VolumeMetadata

    Metadata associated to a volume.

    https://en.wikipedia.org/wiki/Volume_(computing)

    interface VolumeMetadata {
        available?: number;
        error?: string | Error;
        fsid?: string;
        fstype?: string;
        isReadOnly?: boolean;
        isSystemVolume?: boolean;
        label?: string;
        mountFrom?: string;
        mountName?: string;
        mountPoint: string;
        protocol?: string;
        remote: boolean;
        remoteHost?: string;
        remoteShare?: string;
        remoteUser?: string;
        size?: number;
        status?: string;
        subvol?: string;
        subvolid?: number;
        subvolumeUuid?: string;
        uri?: string;
        used?: number;
        uuid?: string;
        volumeRole?: string;
        zfsDatasetGuid?: string;
        zfsPoolGuid?: string;
    }

    Hierarchy (View Summary)

    Index
    available? error? fsid? fstype? isReadOnly? isSystemVolume? label? mountFrom? mountName? mountPoint protocol? remote remoteHost? remoteShare? remoteUser? size? status? subvol? subvolid? subvolumeUuid? uri? used? uuid? volumeRole? zfsDatasetGuid? zfsPoolGuid?
    available?: number

    Available size in bytes

    error?: string | Error

    If there are non-critical errors while extracting metadata, those errors may be added to this field.

    fsid?: string

    A quick filesystem identifier read from statfs(2)'s f_fsid, rendered as a 16-character lowercase hex string.

    Currently populated on ZFS, where it is normally distinct per dataset and stable across remount, reboot, and rename. It is not immutable: OpenZFS may remap it to resolve an active collision between duplicated datasets. Treat it as a current identity or fallback, not the sole durable identity.

    This is not the authoritative ZFS guid property. Enable Options.includeZfsGuids to populate zfsDatasetGuid and zfsPoolGuid. Undefined on non-ZFS filesystems.

    fstype?: string

    The type of file system on the volume, like ext4, apfs, or ntfs.

    Note: on Windows this may show as "ntfs" for remote filesystems, as that is how the filesystem is presented to the OS.

    isReadOnly?: boolean

    Whether the volume is mounted read-only.

    Examples of read-only volumes include the macOS APFS system snapshot at /, mounted ISO images, and write-protected media.

    Note that the macOS root volume (/) UUID changes on every OS update, so consumers should avoid using it for persistent identification.

    isSystemVolume?: boolean

    Indicates if this volume is primarily for system use (e.g., swap, snap loopbacks, EFI boot, or only system directories).

    On macOS, the sealed APFS system snapshot at / is detected natively via MNT_SNAPSHOT; other infrastructure volumes under /System/Volumes/* are detected via APFS volume roles (IOKit). Note that /System/Volumes/Data is not a system volume — it holds all user data, accessed via firmlinks.

    Options.systemPathPatterns and Options.systemFsTypes

    label?: string

    The name of the partition

    mountFrom?: string

    Path to the device or service that the mountpoint is from.

    Examples include /dev/sda1, nfs-server:/export, //username@remoteHost/remoteShare, or //cifs-server/share.

    May be undefined for remote volumes.

    mountName?: string

    The name of the mount. This may match the resolved mountPoint.

    mountPoint: string

    Mount location (like "/" or "C:"). Explicit Linux path queries may return a file path when that file is itself a bind-mount target. Public volume enumeration omits detected non-directory targets; unprobed remote targets are retained when skipNetworkVolumes is true.

    protocol?: string

    Protocol used to access the share.

    remote: boolean

    Does the protocol seem to be a remote filesystem?

    remoteHost?: string

    If remote, the ip or hostname hosting the share (like "rusty" or "10.1.1.3")

    remoteShare?: string

    If remote, the name of the share (like "homes")

    remoteUser?: string

    If remote, may include the username used to access the share.

    This will be undefined on NFS and other remote filesystem types that do authentication out of band.

    size?: number

    Total size in bytes

    status?: string

    On Windows, returns the health status of the volume.

    Note that this is only available on Windows, as both Linux and macOS are prohibitively expensive, requiring forking fsck -N or diskutil verifyVolume.

    If there are non-critical errors while extracting metadata, those error messages may be added to this field (say, from blkid).

    VolumeHealthStatuses for values returned by Windows.

    subvol?: string

    On btrfs, the subvolume path this mount exposes, taken verbatim from the subvol= mount option (e.g. /@ or /@home). Undefined on non-btrfs volumes.

    Several mount points can be distinct subvolumes of one btrfs filesystem and therefore share a single filesystem-level VolumeMetadata.uuid. subvol and subvolid distinguish such siblings. Note that the subvol path changes if the subvolume is renamed or moved; for a rename-stable identifier prefer VolumeMetadata.subvolumeUuid.

    subvolid?: number

    On btrfs, the numeric subvolume id from the subvolid= mount option (e.g. 256, 257). Undefined on non-btrfs volumes.

    Stable across remount/reboot on a given filesystem, but not unique across filesystems and not preserved by btrfs send/receive. See subvol for context and VolumeMetadata.subvolumeUuid for a stronger identifier.

    subvolumeUuid?: string

    On btrfs, the UUID of the individual subvolume mounted here, read from the subvolume's root item via the BTRFS_IOC_GET_SUBVOL_INFO ioctl (kernel

    = 4.18, unprivileged). Rendered as a canonical lowercase hyphenated UUID. Undefined on non-btrfs volumes, and on kernels/builds where the ioctl is unavailable.

    Unlike uuid (the filesystem UUID, shared by all subvolumes) and MountPoint.subvolid (stable only within one filesystem), this is the strongest per-subvolume identifier:

    • stable across remount/reboot;
    • btrfs send/receive preserves the source subvolume's UUID as the destination's received_uuid (the destination itself gets a fresh UUID);
    • a snapshot gets a fresh UUID and records its origin as parent_uuid.

    This makes it suitable for persistent per-subvolume identity where the filesystem uuid would collide across siblings.

    uri?: string

    We can sometimes fetch a URI of the resource (like "smb://server/share" or "file:///media/user/usb")

    used?: number

    Used size in bytes

    uuid?: string

    UUID for the volume, like "c9b08f6e-b392-11ef-bf19-4b13bb7db4b4".

    On windows, this may be the 128-bit volume UUID, but if that is not available, like in the case of remote volumes, we fallback to the 32-bit volume serial number, rendered in lowercase hexadecimal.

    Note that on btrfs this is the filesystem UUID (keyed on the block device by libblkid), so every subvolume of one filesystem reports the same value. Use subvolumeUuid (and/or MountPoint.subvolid) to distinguish sibling subvolumes.

    volumeRole?: string

    The APFS volume role, if available. Only present on macOS for APFS volumes.

    Common roles: "System", "Data", "VM", "Preboot", "Recovery", "Update", "Hardware", "xART", "Prelogin", "Backup".

    Used for system volume detection: volumes with a non-"Data" role and MNT_DONTBROWSE are classified as system volumes.

    https://eclecticlight.co/2024/11/21/how-do-apfs-volume-roles-work/

    zfsDatasetGuid?: string

    The authoritative unsigned 64-bit ZFS dataset guid property, rendered as a decimal string to avoid JavaScript precision loss. The GUID does not change during the dataset's lifetime.

    Linux ZFS only, and populated only when Options.includeZfsGuids is true and the external zfs command succeeds. Kept separate from zfsPoolGuid so consumers can choose lineage or copy-level identity semantics.

    zfsPoolGuid?: string

    The authoritative unsigned 64-bit ZFS pool guid property, rendered as a decimal string to avoid JavaScript precision loss.

    Linux ZFS only, and populated only when Options.includeZfsGuids is true and the external zpool command succeeds. An administrator can change this value explicitly with zpool reguid.

    Settings
    Member Visibility

    On This Page
    Properties