snapshot

Documentation

Index

• Constants
• func Cleanup(targetRoot string) error
• func CloneTreeInto(scratchDir string) error
• func CopyFilesInto(fileSpecs []string, destDir string, opts *CopyFileOptions) error
• func ExpectedCloneContent() []string
• func ExpectedCloneGPUContent() []string
• func ExpectedCloneNetContent() []string
• func ExpectedClonePCIContent() []string
• func ExpectedCloneStaticContent() []string
• func OpenDestination(snapshotName string) (*os.File, error)
• func PackFrom(snapshotName, sourceRoot string) error
• func PackWithWriter(fw io.Writer, sourceRoot string) error
• func SetTraceFunction(fn func(msg string, args ...interface{}))
• func Unpack(snapshotName string) (string, error)
• func UnpackInto(snapshotName, targetRoot string, flags uint) (bool, error)
• func Untar(root string, r io.Reader) error
• func ValidateClonedTree(fileSpecs []string, clonedDir string) ([]string, error)
• type CopyFileOptions

Constants

const (
	// If set, `ghw` will not unpack the snapshot in the user-supplied directory
	// unless the aforementioned directory is empty.
	OwnTargetDirectory = 1 << iota
)

const (
	TargetRoot = "ghw-snapshot-*"
)

Functions

func Cleanup

func Cleanup(targetRoot string) error

Clanup removes the unpacket snapshot from the target root. Please not that the environs variable `GHW_SNAPSHOT_PRESERVE`, if set, will make this function silently skip.

func CloneTreeInto

func CloneTreeInto(scratchDir string) error

CloneTreeInto copies all the pseudofiles that ghw will consume into the root `scratchDir`, preserving the hieratchy.

func CopyFilesInto

func CopyFilesInto(fileSpecs []string, destDir string, opts *CopyFileOptions) error

CopyFilesInto copies all the given glob files specs in the given `destDir` directory, preserving the directory structure. This means you can provide a deeply nested filespec like - /some/deeply/nested/file* and you DO NOT need to build the tree incrementally like - /some/ - /some/deeply/ ... all glob patterns supported in `filepath.Glob` are supported.

func ExpectedCloneContent

func ExpectedCloneContent() []string

ExpectedCloneContent return a slice of glob patterns which represent the pseudofiles ghw cares about. The intended usage of this function is to validate a clone tree, checking that the content matches the expectations. Beware: the content is host-specific, because the content pertaining some subsystems, most notably PCI, is host-specific and unpredictable.

func ExpectedCloneGPUContent

func ExpectedCloneGPUContent() []string

ExpectedCloneGPUContent returns a slice of strings pertaining to the GPU devices ghw cares about. We cannot use a static list because we want to grab only the first cardX data (see comment in pkg/gpu/gpu_linux.go) Additionally, we want to make sure to clone the backing device data.

func ExpectedCloneNetContent

func ExpectedCloneNetContent() []string

ExpectedCloneNetContent returns a slice of strings pertaning to the network interfaces ghw cares about. We cannot use a static list because we want to filter away the virtual devices, which ghw doesn't concern itself about. So we need to do some runtime discovery. Additionally, we want to make sure to clone the backing device data.

func ExpectedClonePCIContent

func ExpectedClonePCIContent() []string

ExpectedClonePCIContent return a slice of glob patterns which represent the pseudofiles ghw cares about, pertaining to PCI devices only. Beware: the content is host-specific, because the PCI topology is host-dependent and unpredictable.

func ExpectedCloneStaticContent

func ExpectedCloneStaticContent() []string

ExpectedCloneStaticContent return a slice of glob patterns which represent the pseudofiles ghw cares about, and which are independent from host specific topology or configuration, thus are safely represented by a static slice - e.g. they don't need to be discovered at runtime.

func OpenDestination

func OpenDestination(snapshotName string) (*os.File, error)

OpenDestination opens the `snapshotName` file for writing, bailing out if the file seems to exist and have existing content already. This is done to avoid accidental overwrites.

func PackFrom

func PackFrom(snapshotName, sourceRoot string) error

PackFrom creates the snapshot named `snapshotName` from the directory tree whose root is `sourceRoot`.

func PackWithWriter

func PackWithWriter(fw io.Writer, sourceRoot string) error

PakcWithWriter creates a snapshot sending all the binary data to the given `fw` writer. The snapshot is made from the directory tree whose root is `sourceRoot`.

func SetTraceFunction

func SetTraceFunction(fn func(msg string, args ...interface{}))

func Unpack

func Unpack(snapshotName string) (string, error)

Unpack expands the given snapshot in a temporary directory managed by `ghw`. Returns the path of that directory.

func UnpackInto

func UnpackInto(snapshotName, targetRoot string, flags uint) (bool, error)

UnpackInto expands the given snapshot in a client-supplied directory. Returns true if the snapshot was actually unpacked, false otherwise

func Untar

func Untar(root string, r io.Reader) error

Untar extracts data from the given reader (providing data in tar.gz format) and unpacks it in the given directory.

func ValidateClonedTree

func ValidateClonedTree(fileSpecs []string, clonedDir string) ([]string, error)

ValidateClonedTree checks the content of a cloned tree, whose root is `clonedDir`, against a slice of glob specs which must be included in the cloned tree. Is not wrong, and this functions doesn't enforce this, that the cloned tree includes more files than the necessary; ghw will just ignore the files it doesn't care about. Returns a slice of glob patters expected (given) but not found in the cloned tree, and the error during the validation (if any).

Types

type CopyFileOptions

type CopyFileOptions struct {
	// IsSymlinkFn allows to control the behaviour when handling a symlink.
	// If this hook returns true, the source file is treated as symlink: the cloned
	// tree will thus contain a symlink, with its path adjusted to match the relative
	// path inside the cloned tree. If return false, the symlink will be deferred.
	// The easiest use case of this hook is if you want to avoid symlinks in your cloned
	// tree (having duplicated content). In this case you can just add a function
	// which always return false.
	IsSymlinkFn func(path string, info os.FileInfo) bool
	// ShouldCreateDirFn allows to control if empty directories listed as clone
	// content should be created or not. When creating snapshots, empty directories
	// are most often useless (but also harmless). Because of this, directories are only
	// created as side effect of copying the files which are inside, and thus directories
	// are never empty. The only notable exception are device driver on linux: in this
	// case, for a number of technical/historical reasons, we care about the directory
	// name, but not about the files which are inside.
	// Hence, this is the only case on which ghw clones empty directories.
	ShouldCreateDirFn func(path string, info os.FileInfo) bool
}

CopyFileOptions allows to finetune the behaviour of the CopyFilesInto function