gofsutil

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 24, 2024 License: Apache-2.0 Imports: 13 Imported by: 0

README

Mount

A portable Go library for filesystem related operations such as mount, format, etc.

Documentation

Overview

Package gofsutil provides many filesystem-specific functions, such as mount, format, etc., and is based largely on k8s.io/pkg/util/mount.

Index

Constants

View Source 
const ProcMountsFields = 9

ProcMountsFields is fields per line in procMountsPath as per https://www.kernel.org/doc/Documentation/filesystems/proc.txt

Variables

View Source 
var (
	// ErrNotImplemented is returned when a platform does not implement
	// the contextual function.
	ErrNotImplemented = errors.New("not implemented")
)

Functions

func BindMount 

func BindMount(
	ctx context.Context,
	source, target string,
	opts ...string) error

BindMount behaves like Mount was called with a "bind" flag set in the options list. 

func EvalSymlinks(ctx context.Context, symPath *string) error

EvalSymlinks evaluates the provided path and updates it to remove any symlinks in its structure, replacing them with the actual path components.

func FormatAndMount 

func FormatAndMount(
	ctx context.Context,
	source, target, fsType string,
	opts ...string) error

FormatAndMount uses unix utils to format and mount the given disk.

func GetDiskFormat 

func GetDiskFormat(ctx context.Context, disk string) (string, error)

GetDiskFormat uses 'lsblk' to see if the given disk is unformatted.

func MakeMountArgs 

func MakeMountArgs(
	ctx context.Context,
	source, target, fsType string,
	opts ...string) []string

MakeMountArgs makes the arguments to the mount(8) command.

The argument list returned is built as follows: 

mount [-t $fsType] [-o $options] [$source] $target

func Mount 

func Mount(
	ctx context.Context,
	source, target, fsType string,
	opts ...string) error

Mount mounts source to target as fstype with given options.

The parameters 'source' and 'fstype' must be empty strings in case they are not required, e.g. for remount, or for an auto filesystem type where the kernel handles fstype automatically.

The 'options' parameter is a list of options. Please see mount(8) for more information. If no options are required then please invoke Mount with an empty or nil argument.

func RemoveDuplicates 

func RemoveDuplicates(a []string) []string

RemoveDuplicates removes duplicate and empty values from the provided slice of strings and maintains the original order of the list.

This function defers to RemoveDuplicatesExponentialOrdered, a variation of RemoveDuplicatesExponentialUnordered as described in the article "Learning Golang By Benchmarking Set Implementations" by Karl Seguin at https://goo.gl/NTU36K. The variation preserves the slice's original order and has minimal to no impact on performance.

The function's O(n^2) complexity could be altered to O(n) (linear) by using a map[string]struct{} to track unique elements with zero memory allocation. However, as long as the input data is small, the current implementation is more performant both with respect to both CPU and memory. Given that this function is used to remove duplicate mount options, there should never be a sufficiently large enough dataset that a linear version of this function would be more performant the current implementation.

The function RemoveDuplicatesLinearOrdered is the linear version of this function. If the situation should ever change such that mount options number in the thousands then this function should defer to RemoveDuplicatesLinearOrdered instead of RemoveDuplicatesExponentialOrdered. 

$ go test -run Bench -bench BenchmarkRemoveDuplicates -benchmem -v
goos: darwin
goarch: amd64
pkg: github.com/thecodeteam/gofsutil
BenchmarkRemoveDuplicates_Exponential_Ordered___SmallData-8   	20000000	       121 ns/op	       0 B/op	       0 allocs/op
BenchmarkRemoveDuplicates_Exponential_Unordered_SmallData-8   	20000000	        99.0 ns/op	       0 B/op	       0 allocs/op
BenchmarkRemoveDuplicates_Linear______Ordered___SmallData-8   	 2000000	       715 ns/op	     288 B/op	       1 allocs/op
BenchmarkRemoveDuplicates_Exponential_Ordered___BigData-8     	   20000	     84731 ns/op	       0 B/op	       0 allocs/op
BenchmarkRemoveDuplicates_Exponential_Unordered_BigData-8     	   10000	    156660 ns/op	       0 B/op	       0 allocs/op
BenchmarkRemoveDuplicates_Linear______Ordered___BigData-8     	   50000	     36971 ns/op	   20512 B/op	       2 allocs/op
PASS
ok  	github.com/thecodeteam/gofsutil	22.085s

func RemoveDuplicatesExponentialOrdered 

func RemoveDuplicatesExponentialOrdered(a []string) []string

RemoveDuplicatesExponentialOrdered removes duplicate and empty values from the provided slice of strings using an exponentially complex algorithm and maintains the original order of the list.

func RemoveDuplicatesExponentialUnordered 

func RemoveDuplicatesExponentialUnordered(a []string) []string

RemoveDuplicatesExponentialUnordered removes duplicate and empty values from the provided slice of strings using an exponentially complex algorithm and does not maintain the original order of the list.

func RemoveDuplicatesLinearOrdered 

func RemoveDuplicatesLinearOrdered(a []string) []string

RemoveDuplicatesLinearOrdered removes duplicate and empty values from the provided slice of strings using a linearly complex algorithm and maintains the original order of the list.

func Unmount 

func Unmount(ctx context.Context, target string) error

Unmount unmounts the target.

func ValidateDevice added in v0.1.2 

func ValidateDevice(ctx context.Context, source string) (string, error)

ValidateDevice evalutes the specified path and determines whether or not it is a valid device. If true then the provided path is evaluated and returned as an absolute path without any symlinks. Otherwise an empty string is returned.

Types

type Entry 

type Entry struct {
	// Root of the mount within the filesystem.
	Root string

	// MountPoint relative to the process's root
	MountPoint string

	// MountOpts are per-mount options.
	MountOpts []string

	// FSType is the name of filesystem of the form "type[.subtype]".
	FSType string

	// MountSource is filesystem specific information or "none"
	MountSource string
}

Entry is a superset of Info and maps to the fields of a mount table entry: 

(1) mount ID:  unique identifier of the mount (may be reused after umount)
(2) parent ID:  ID of parent (or of self for the top of the mount tree)
(3) major:minor:  value of st_dev for files on filesystem
(4) root:  root of the mount within the filesystem
(5) mount point:  mount point relative to the process's root
(6) mount options:  per mount options
(7) optional fields:  zero or more fields of the form "tag[:value]"
(8) separator:  marks the end of the optional fields
(9) filesystem type:  name of filesystem of the form "type[.subtype]"
(10) mount source:  filesystem specific information or "none"
(11) super options:  per super block options

type EntryScanFunc 

type EntryScanFunc func(
	ctx context.Context,
	entry Entry,
	cache map[string]Entry) (Info, bool, error)

EntryScanFunc defines the signature of the function that is optionally provided to the functions in this package that scan the mount table. The mount entry table is ignored when this function returns a false value or error.

func DefaultEntryScanFunc 

func DefaultEntryScanFunc() EntryScanFunc

DefaultEntryScanFunc returns the default entry scan function.

type FS 

type FS struct {

	// ScanEntry is the function used to process mount table entries.
	ScanEntry EntryScanFunc
}

FS provides many filesystem-specific functions, such as mount, format, etc.

func (*FS) BindMount 

func (fs *FS) BindMount(
	ctx context.Context,
	source, target string,
	options ...string) error

BindMount behaves like Mount was called with a "bind" flag set in the options list.

func (*FS) FormatAndMount 

func (fs *FS) FormatAndMount(
	ctx context.Context,
	source, target, fsType string,
	options ...string) error

FormatAndMount uses unix utils to format and mount the given disk.

func (*FS) GetDevMounts 

func (fs *FS) GetDevMounts(ctx context.Context, dev string) ([]Info, error)

GetDevMounts returns a slice of all mounts for the provided device.

func (*FS) GetDiskFormat 

func (fs *FS) GetDiskFormat(ctx context.Context, disk string) (string, error)

GetDiskFormat uses 'lsblk' to see if the given disk is unformatted.

func (*FS) GetMounts 

func (fs *FS) GetMounts(ctx context.Context) ([]Info, error)

GetMounts returns a slice of all the mounted filesystems.

* Linux hosts use mount_namespaces to obtain mount information. 

Support for mount_namespaces was introduced to the Linux kernel
in 2.2.26 (http://man7.org/linux/man-pages/man5/proc.5.html) on
2004/02/04.

The kernel documents the contents of "/proc/<pid>/mountinfo" at
https://www.kernel.org/doc/Documentation/filesystems/proc.txt.
  • Darwin hosts parse the output of the "mount" command to obtain mount information.

func (*FS) Mount 

func (fs *FS) Mount(
	ctx context.Context,
	source, target, fsType string,
	options ...string) error

Mount mounts source to target as fstype with given options.

The parameters 'source' and 'fstype' must be empty strings in case they are not required, e.g. for remount, or for an auto filesystem type where the kernel handles fstype automatically.

The 'options' parameter is a list of options. Please see mount(8) for more information. If no options are required then please invoke Mount with an empty or nil argument.

func (*FS) Unmount 

func (fs *FS) Unmount(ctx context.Context, target string) error

Unmount unmounts the target.

func (*FS) ValidateDevice added in v0.1.1 

func (fs *FS) ValidateDevice(
	ctx context.Context, source string) (string, error)

ValidateDevice evalutes the specified path and determines whether or not it is a valid device. If true then the provided path is evaluated and returned as an absolute path without any symlinks. Otherwise an empty string is returned.

type Info 

type Info struct {
	// Device is the filesystem path of the device to which the filesystem is
	// mounted.
	Device string

	// Path is the filesystem path to which Device is mounted.
	Path string

	// Source may be set to one of two values:
	//
	//   1. If this is a bind mount created with "bindfs" then Source
	//      is set to the filesystem path (absolute, no symlinks)
	//      bind mounted to Path.
	//
	//   2. If this is any other type of mount then Source is set to
	//      a concatenation of the mount source and the root of
	//      the mount within the file system (fields 10 & 4 from
	//      the section on /proc/<pid>/mountinfo at
	//      https://www.kernel.org/doc/Documentation/filesystems/proc.txt).
	//
	// It is not possible to diffentiate a native bind mount from a
	// non-bind mount after the native bind mount has been created.
	// Therefore, while the Source field will be set to the filesystem
	// path bind mounted to Path for native bind mounts, the value of
	// the Source field can in no way be used to determine *if* a mount
	// is a bind mount.
	Source string

	// Type is the filesystem type.
	Type string

	// Opts are the mount options (https://linux.die.net/man/8/mount)
	// used to mount the filesystem.
	Opts []string
}

Info describes a mounted filesystem.

Please note that all fields that represent filesystem paths must be absolute and not contain any symlinks.

func GetDevMounts 

func GetDevMounts(ctx context.Context, dev string) ([]Info, error)

GetDevMounts returns a slice of all mounts for the provided device.

func GetMounts 

func GetMounts(ctx context.Context) ([]Info, error)

GetMounts returns a slice of all the mounted filesystems.

* Linux hosts use mount_namespaces to obtain mount information. 

Support for mount_namespaces was introduced to the Linux kernel
in 2.2.26 (http://man7.org/linux/man-pages/man5/proc.5.html) on
2004/02/04.

The kernel documents the contents of "/proc/<pid>/mountinfo" at
https://www.kernel.org/doc/Documentation/filesystems/proc.txt.
  • Darwin hosts parse the output of the "mount" command to obtain mount information.

func ReadProcMountsFrom 

func ReadProcMountsFrom(
	ctx context.Context,
	file io.Reader,
	quick bool,
	expectedFields int,
	scanEntry EntryScanFunc) ([]Info, uint32, error)

ReadProcMountsFrom parses the contents of a mount table file, typically "/proc/self/mountinfo".

From https://www.kernel.org/doc/Documentation/filesystems/proc.txt:

3.5 /proc/<pid>/mountinfo - Information about mounts --------------------------------------------------------

This file contains lines of the form:

36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 - ext3 /dev/root rw,errors=continue (1)(2)(3) (4) (5) (6) (7) (8) (9) (10) (11)

(1) mount ID: unique identifier of the mount (may be reused after umount) (2) parent ID: ID of parent (or of self for the top of the mount tree) (3) major:minor: value of st_dev for files on filesystem (4) root: root of the mount within the filesystem (5) mount point: mount point relative to the process's root (6) mount options: per mount options (7) optional fields: zero or more fields of the form "tag[:value]" (8) separator: marks the end of the optional fields (9) filesystem type: name of filesystem of the form "type[.subtype]" (10) mount source: filesystem specific information or "none" (11) super options: per super block options

Parsers should ignore all unrecognised optional fields. Currently the possible optional fields are:

shared:X mount is shared in peer group X master:X mount is slave to peer group X propagate_from:X mount is slave and receives propagation from peer group X (*) unbindable mount is unbindable

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.