storage

README

Overview

The Storage package provides uniform access to the underlying storage layer for Windows, Linux and Mac OS. Implementations are kept identical between platforms to ensure testability through interfaces by consumers. This package supports Physical and Removable Hard Disk storage. Other storage types are not available.

Features

• Device and Partition Support - Storage devices returned by this library are described with both device and partitioning attributes. Consumers can use the various accessor methods to inspect the contents of a device and evaluate it for use.

• Support for Formatting and Partitioning - Storage devices can be wiped, partitioned and formatted as needed.

• Support for Mounting/Dismounting/Ejecting - Storage devices can be, mounted, dismounted or ejected.

• Consistent implementations - Storage layers are accessed using the same methods, regardless of platform. In other words, tasks like searching for a drive are accomplished the same way on Windows, Linux or Mac.

• Built for Testing - Consumers of this library can create interfaces in their applications to mock the storage layer, permitting consumers to test expected storage behaviors.

Requirements

Storage utilizes native OS implementations to achieve a uniform result. See the following list for the OS specific requirements.

• Windows - Windows 10 with Powershell 5.0 or higher. Powershell is leveraged to perform many disk management functions.

• Linux - GNU Linux with the parted and label commands available. It is assumed that the user can sudo to root for specific actions.

• Mac - MacOS Mojave or higher with access to the diskutil command.

How to use this library

A few example uses for this library are illustrated below. For additional use cases, see the codebase.

Search for storage devices

This call returns one or more devices if it is successful. Available parameters include an optional deviceID (when searching for a specific device), a minimum and maximum size and and whether or not to return only removable devices.

deviceID := ""          // An empty string searches all devices.
minSize := 1000000000   // 1 GB
maxSize := 100000000000 // 100 GB
removableOnly := true   // Return only removable drives.

// Search removable devices for storage devices that are > 1GB, but < 100GB.
devices, err := storage.Search(deviceID, minSize, maxSize, removableOnly)
if err != nil {
  // Log Error message here.
}

Retrieve a storage device

This call retrieves information about a device and returns an object that you can use to inspect or modify the device.

deviceID := "sda"
device, err := storage.New(deviceID)
if err != nil {
  // Log error message here.
}

Repartition a storage device

Use these calls to repartition a device already previously retrieved and assign a label of "NEWLBL".

if err := device.Wipe(); err != nil {
  // Log error message here.
}

label := "NEWLBL"
if err := device.Partition(label); err != nil {
  // Log error message here.
}

Contact

We have a public discussion list at google-winops@googlegroups.com

Disclaimer

This is not an official Google product.

Documentation

Overview

Package storage provides a unified method to access and modify to both fixed and removable disk storage. Implementations are kept consistent between platforms to permit testing through interfaces by consumers.

Index

• type Device
  • func New(deviceID string) (*Device, error)
  • func Search(deviceID string, minSize, maxSize uint64, removableOnly bool) ([]*Device, error)
  • func (device *Device) DetectPartitions(mount bool) error
  • func (device *Device) Dismount() error
  • func (device *Device) Eject() error
  • func (device *Device) FriendlyName() string
  • func (device *Device) Identifier() string
  • func (device *Device) Partition(label string) error
  • func (device *Device) ProbeDevicePartitions() error
  • func (device *Device) SelectPartition(minSize uint64, fs FileSystem) (*Partition, error)
  • func (device *Device) Size() uint64
  • func (device *Device) Wipe() error
• type FileSystem
• type Partition
  • func (part *Partition) Contents() ([]string, error)
  • func (part *Partition) Erase() error
  • func (part *Partition) Format(label string) error
  • func (part *Partition) Identifier() string
  • func (part *Partition) Label() string
  • func (part *Partition) Mount(base string) error
  • func (part *Partition) MountPoint() string

Types

type Device

type Device struct {
	// contains filtered or unexported fields
}

Device describes a physical device that is currently attached to the system.

func New

func New(deviceID string) (*Device, error)

New takes a unique device ID (e.g. sda) and returns a pointer to a Device that describes the removable disk and its contents or an error.

func Search

func Search(deviceID string, minSize, maxSize uint64, removableOnly bool) ([]*Device, error)

Search performs a device search based on the provided parameters and returns a slice of storage devices that meet the criteria. Parameters are not mandatory. For example, if no deviceID is passed, all deviceID's are considered for the search.

func (*Device) DetectPartitions

func (device *Device) DetectPartitions(mount bool) error

DetectPartitions updates a device with known partition information on Linux.

func (*Device) Dismount

func (device *Device) Dismount() error

Dismount enumerates all the mounted partitions on the device and unmounts them. It is typically used with a flag when safety after writes to disk are desired. Errors are only thrown when a mountpoint is found but cannot be unmounted.

func (*Device) Eject

func (device *Device) Eject() error

Eject powers off the device.

func (*Device) FriendlyName

func (device *Device) FriendlyName() string

FriendlyName returns a human-readable friendly name for the device using available make and model information.

func (*Device) Identifier

func (device *Device) Identifier() string

Identifier returns a human-readable identifier for the device using the available device ID.

func (*Device) Partition

func (device *Device) Partition(label string) error

Partition sets up a GPT-Style partition scheme, and creates a single FAT32 partition using the maximum amount of available space. Linux automatically assigns a GPT GUID (System or EFI) to the partition, meaning it does not automatically mount on Windows, however this is handled automatically in this library for Windows.

func (*Device) ProbeDevicePartitions

func (device *Device) ProbeDevicePartitions() error

ProbeDevicePartitions forces the operating system to reexamine the partition table information on Linux.

func (*Device) SelectPartition

func (device *Device) SelectPartition(minSize uint64, fs FileSystem) (*Partition, error)

SelectPartition enumerates the partitions on a device and returns the first partition that matches the criteria. Size and type are valid criteria. A size of zero is treated as "any size". A blank type is treated as "any type". If both input parameters are set to any, the first available partition is returned, or an error if there are no avaialble partitions.

func (*Device) Size

func (device *Device) Size() uint64

Size returns the size of the device in bytes.

func (*Device) Wipe

func (device *Device) Wipe() error

Wipe removes all filesystem and partition table signatures from the device.

type FileSystem

type FileSystem string

FileSystem provides standardized file system descriptions (e.g. FAT32, NTFS)

const (
	// NTFS is the NTFS filesystem.
	NTFS FileSystem = "NTFS"
	// ExFAT is the ExFAT filesystem.
	ExFAT FileSystem = "exFAT"
	// FAT is the FAT filesystem.
	FAT FileSystem = "FAT"
	// FAT32 is the FAT32 filesystem.
	FAT32 FileSystem = "FAT32"
	// APFS is the Apple APFS filesystem.
	APFS FileSystem = "APFS"
	// UnknownFS is an unknown filesystem.
	UnknownFS FileSystem = "Unknown"

	// UnknownModel represents devices of unidentified models and makes.
	UnknownModel = "Unknown"
)

type Partition

type Partition struct {
	// contains filtered or unexported fields
}

Partition describes a disk partition using platform-independent paths and terminology. Partitions are considered immutable. If a partition is changed it should be redetected to ensure data integrity.

func (*Partition) Contents

func (part *Partition) Contents() ([]string, error)

Contents returns a list of the contents of a partition.

func (*Partition) Erase

func (part *Partition) Erase() error

Erase removes all files from a mounted partition. The erase operation is typically used when contents of a partition need to be refreshed, but a full reformat is not desirable, such as when a refresh is needed but the user is not running with elevated rights.

func (*Partition) Format

func (part *Partition) Format(label string) error

Format formats the corresponding partition as vfat/FAT32 and sets the partition label.

func (*Partition) Identifier

func (part *Partition) Identifier() string

Identifier returns the identifier for the partition.

func (*Partition) Label

func (part *Partition) Label() string

Label returns the assigned label of the partition.

func (*Partition) Mount

func (part *Partition) Mount(base string) error

Mount reads the current mount point for the partition. If it is empty and the file system is readable, the device is mounted. If the device is already mounted, we simply do nothing and return.

func (*Partition) MountPoint

func (part *Partition) MountPoint() string

MountPoint returns the mount point of the partition.