filesystem

package
v0.9.0-beta1 Latest Latest
Warning

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

 Go to latest Published: Apr 29, 2019 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package filesystem provides various filesystem utility methods either not provided by the Go standard library or requiring a more optimized implementation. It also provides filesystem watching facilities.

Index

Constants

View Source 
const (
	// ModePermissionsMask is a bit mask that isolates portable permission bits.
	ModePermissionsMask = Mode(0777)

	// ModePermissionUserRead is the user readable bit.
	ModePermissionUserRead = Mode(0400)
	// ModePermissionUserWrite is the user writable bit.
	ModePermissionUserWrite = Mode(0200)
	// ModePermissionUserExecute is the user executable bit.
	ModePermissionUserExecute = Mode(0100)
	// ModePermissionGroupRead is the group readable bit.
	ModePermissionGroupRead = Mode(0040)
	// ModePermissionGroupWrite is the group writable bit.
	ModePermissionGroupWrite = Mode(0020)
	// ModePermissionGroupExecute is the group executable bit.
	ModePermissionGroupExecute = Mode(0010)
	// ModePermissionOthersRead is the others readable bit.
	ModePermissionOthersRead = Mode(0004)
	// ModePermissionOthersWrite is the others writable bit.
	ModePermissionOthersWrite = Mode(0002)
	// ModePermissionOthersExecute is the others executable bit.
	ModePermissionOthersExecute = Mode(0001)
)
View Source 
const (
	// ModeTypeMask is a bit mask that isolates type information. After masking,
	// the resulting value can be compared with any of the ModeType* values
	// (other than ModeTypeMask).
	ModeTypeMask = Mode(unix.S_IFMT)
	// ModeTypeDirectory represents a directory.
	ModeTypeDirectory = Mode(unix.S_IFDIR)
	// ModeTypeFile represents a file.
	ModeTypeFile = Mode(unix.S_IFREG)
	// ModeTypeSymbolicLink represents a symbolic link.
	ModeTypeSymbolicLink = Mode(unix.S_IFLNK)
)
View Source 
const (

	// MutagenDirectoryName is the name of the Mutagen control directory inside
	// the user's home directory.
	MutagenDirectoryName = ".mutagen"
)
View Source 
const (
	// TemporaryNamePrefix is the file name prefix to use for intermediate
	// temporary files created by Mutagen. Using this prefix guarantees that any
	// such files will be ignored by filesystem watching and synchronization
	// scans. It may be suffixed with additional information if desired.
	TemporaryNamePrefix = ".mutagen-temporary-"
)

Variables

View Source 
var ErrUnsupportedOpenType = errors.New("unsupported open type")

ErrUnsupportedOpenType indicates that the filesystem entry at the specified path is not supported as a traversal root.

View Source 
var HomeDirectory string

HomeDirectory is the cached path to the current user's home directory.

View Source 
var MutagenConfigurationPath string

MutagenConfigurationPath is the path to the Mutagen configuration file.

View Source 
var ProbeMode_name = map[int32]string{
	0: "ProbeModeDefault",
	1: "ProbeModeProbe",
	2: "ProbeModeAssume",
}
View Source 
var ProbeMode_value = map[string]int32{
	"ProbeModeDefault": 0,
	"ProbeModeProbe":   1,
	"ProbeModeAssume":  2,
}
View Source 
var WatchMode_name = map[int32]string{
	0: "WatchModeDefault",
	1: "WatchModePortable",
	2: "WatchModeForcePoll",
	3: "WatchModeNoWatch",
}
View Source 
var WatchMode_value = map[string]int32{
	"WatchModeDefault":   0,
	"WatchModePortable":  1,
	"WatchModeForcePoll": 2,
	"WatchModeNoWatch":   3,
}

Functions

func DecomposesUnicode 

func DecomposesUnicode(directory *Directory, probeMode ProbeMode) (bool, error)

DecomposesUnicode determines whether or not the specified directory (and its underlying filesystem) decomposes Unicode filenames.

func DecomposesUnicodeByPath added in v0.8.0 

func DecomposesUnicodeByPath(path string, probeMode ProbeMode) (bool, error)

DecomposesUnicodeByPath determines whether or not the filesystem on which the directory at the specified path resides decomposes Unicode filenames.

func DirectoryContentsByPath added in v0.8.0 

func DirectoryContentsByPath(path string) ([]os.FileInfo, error)

DirectoryContentsByPath returns the contents of the directory at the specified path. The ordering of the contents is non-deterministic.

func IsCrossDeviceError added in v0.8.0 

func IsCrossDeviceError(err error) bool

IsCrossDeviceError checks whether or not an error returned from rename represents a cross-device error.

func IsTemporaryFileName added in v0.8.0 

func IsTemporaryFileName(name string) bool

IsTemporaryFileName determines whether or not a file name (not a file path) is the name of an intermediate temporary file used by Mutagen.

func Mutagen 

func Mutagen(create bool, subpath ...string) (string, error)

Mutagen computes (and optionally creates) subdirectories inside the Mutagen directory (~/.mutagen).

func Normalize 

func Normalize(path string) (string, error)

Normalize normalizes a path, expanding home directory tildes, converting it to an absolute path, and cleaning the result.

func OpenDirectory added in v0.8.0 

func OpenDirectory(path string, allowSymbolicLinkLeaf bool) (*Directory, *Metadata, error)

OpenDirectory is a convenience wrapper around Open that requires the result to be a directory.

func OpenFile added in v0.8.0 

func OpenFile(path string, allowSymbolicLinkLeaf bool) (ReadableFile, *Metadata, error)

OpenFile is a convenience wrapper around Open that requires the result to be a file.

func PreservesExecutability 

func PreservesExecutability(directory *Directory, probeMode ProbeMode) (bool, error)

PreservesExecutability determines whether or not the specified directory (and its underlying filesystem) preserves POSIX executability bits.

func PreservesExecutabilityByPath added in v0.8.0 

func PreservesExecutabilityByPath(path string, probeMode ProbeMode) (bool, error)

PreservesExecutabilityByPath determines whether or not the filesystem on which the directory at the specified path resides preserves POSIX executability bits. It allows for the path leaf to be a symbolic link.

func Rename added in v0.8.0 

func Rename(
	sourceDirectory *Directory, sourceNameOrPath string,
	targetDirectory *Directory, targetNameOrPath string,
) error

Rename performs an atomic rename operation from one filesystem location (the source) to another (the target). Each location can be specified in one of two ways: either by a combination of directory and (non-path) name or by path (with corresponding nil Directory object). Different specification mechanisms can be used for each location.

This function does not support cross-device renames. To detect whether or not an error is due to an attempted cross-device rename, use the IsCrossDeviceError function.

func SetPermissionsByPath added in v0.8.0 

func SetPermissionsByPath(path string, ownership *OwnershipSpecification, mode Mode) error

SetPermissionsByPath sets the permissions on the content at the specified path. Ownership information is set first, followed by permissions extracted from the mode using ModePermissionsMask. Ownership setting can be skipped completely by providing a nil OwnershipSpecification or a specification with both components unset. An OwnershipSpecification may also include only certain components, in which case only those components will be set. Permission setting can be skipped by providing a mode value that yields 0 after permission bit masking.

func Walk added in v0.5.0 

func Walk(root string, visitor filepath.WalkFunc) error

Walk provides a faster implementation of path/filepath.Walk with slightly different semantics. In particular, it only walks directory contents after metadata for the directory has been collected and does not sort entries by name. It gains speed by avoiding sorting and, more importantly, using os.File.Readdir for vastly more efficient traversal on Windows.

func Watch 

func Watch(context context.Context, root string, events chan struct{}, mode WatchMode, pollInterval uint32)

TODO: Document that this function closes the events channel when the watch is cancelled. TODO: Document that this function will always succeed in one way or another (it doesn't have any total failure modes) and won't exit until the associated context is cancelled. TODO: Document that the events channel must be buffered. TODO: Document that the polling interval must be non-0.

func WriteFileAtomic 

func WriteFileAtomic(path string, data []byte, permissions os.FileMode) error

WriteFileAtomic writes a file to disk in an atomic fashion by using an intermediate temporary file that is swapped in place using a rename operation.

Types

type Directory added in v0.8.0 

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

Directory represents a directory on disk and provides race-free operations on the directory's contents. All of its operations avoid the traversal of symbolic links.

func (*Directory) Close added in v0.8.0 

func (d *Directory) Close() error

Close closes the directory.

func (*Directory) CreateDirectory added in v0.8.0 

func (d *Directory) CreateDirectory(name string) error

CreateDirectory creates a new directory with the specified name inside the directory. The directory will be created with user-only read/write/execute permissions. 

func (d *Directory) CreateSymbolicLink(name, target string) error

CreateSymbolicLink creates a new symbolic link with the specified name and target inside the directory. The symbolic link is created with the default system permissions (which, generally speaking, don't apply to the symbolic link itself).

func (*Directory) CreateTemporaryFile added in v0.8.0 

func (d *Directory) CreateTemporaryFile(pattern string) (string, WritableFile, error)

CreateTemporaryFile creates a new temporary file using the specified name pattern inside the directory. Pattern behavior follows that of io/ioutil.TempFile. The file will be created with user-only read/write permissions.

func (*Directory) OpenDirectory added in v0.8.0 

func (d *Directory) OpenDirectory(name string) (*Directory, error)

OpenDirectory opens the directory within the directory specified by name.

func (*Directory) OpenFile added in v0.8.0 

func (d *Directory) OpenFile(name string) (ReadableFile, error)

OpenFile opens the file within the directory specified by name.

func (*Directory) ReadContentMetadata added in v0.8.0 

func (d *Directory) ReadContentMetadata(name string) (*Metadata, error)

ReadContentMetadata reads metadata for the content within the directory specified by name.

func (*Directory) ReadContentNames added in v0.8.0 

func (d *Directory) ReadContentNames() ([]string, error)

ReadContentNames queries the directory contents and returns their base names. It does not return "." or ".." entries.

func (*Directory) ReadContents added in v0.8.0 

func (d *Directory) ReadContents() ([]*Metadata, error)

ReadContents queries the directory contents and their associated metadata. While the results of this function can be computed as a combination of ReadContentNames and ReadContentMetadata, this function may be significantly faster than a naïve combination of the two (e.g. due to parallelized fstatat calls on POSIX systems and the usage of FindFirstFile/FindNextFile infrastructure on Windows). This function doesn't return metadata for "." or ".." entries. 

func (d *Directory) ReadSymbolicLink(name string) (string, error)

ReadSymbolicLink reads the target of the symbolic link within the directory specified by name.

func (*Directory) RemoveDirectory added in v0.8.0 

func (d *Directory) RemoveDirectory(name string) error

RemoveDirectory deletes a directory with the specified name inside the directory. The removal target must be empty.

func (*Directory) RemoveFile added in v0.8.0 

func (d *Directory) RemoveFile(name string) error

RemoveFile deletes a file with the specified name inside the directory. 

func (d *Directory) RemoveSymbolicLink(name string) error

RemoveSymbolicLink deletes a symbolic link with the specified name inside the directory.

func (*Directory) SetPermissions added in v0.8.0 

func (d *Directory) SetPermissions(name string, ownership *OwnershipSpecification, mode Mode) error

SetPermissions sets the permissions on the content within the directory specified by name. Ownership information is set first, followed by permissions extracted from the mode using ModePermissionsMask. Ownership setting can be skipped completely by providing a nil OwnershipSpecification or a specification with both components unset. An OwnershipSpecification may also include only certain components, in which case only those components will be set. Permission setting can be skipped by providing a mode value that yields 0 after permission bit masking.

type Locker 

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

Locker provides file locking facilities.

func NewLocker 

func NewLocker(path string, permissions os.FileMode) (*Locker, error)

NewLocker attempts to create a lock with the file at the specified path, creating the file if necessary. The lock is returned in an unlocked state.

func (*Locker) Lock 

func (l *Locker) Lock(block bool) error

Lock attempts to acquire the file lock.

func (*Locker) Unlock 

func (l *Locker) Unlock() error

Unlock releases the file lock.

type Metadata added in v0.8.0 

type Metadata struct {
	// Name is the base name of the filesystem entry.
	Name string
	// Mode is the mode of the filesystem entry.
	Mode Mode
	// Size is the size of the filesystem entry in bytes.
	Size uint64
	// ModificationTime is the modification time of the filesystem entry.
	ModificationTime time.Time
	// DeviceID is the filesystem device ID on which the filesytem entry
	// resides. On Windows systems it is always 0.
	DeviceID uint64
	// FileID is the file ID for the filesystem entry. On Windows systems it is
	// always 0.
	FileID uint64
}

Metadata encodes information about a filesystem entry.

func Open added in v0.8.0 

func Open(path string, allowSymbolicLinkLeaf bool) (io.Closer, *Metadata, error)

Open opens a filesystem path for traversal and operations. It will return either a Directory or ReadableFile object (as an io.Closer for convenient closing access without casting), along with Metadata that can be used to determine the type of object being returned. Unless explicitly specified, this function does not allow the leaf component of path to be a symbolic link (though intermediate components of the path can be symbolic links and will be resolved in the resolution of the path), and an error will be returned if this is the case (though on POSIX systems it will not be ErrUnsupportedOpenType). However, if allowSymbolicLinkLeaf is true, then this function will allow resolution of a path leaf component that's a symbolic link. In this case, the referenced object must still be a directory or regular file, and the returned object will still be either a Directory or ReadableFile.

type Mode added in v0.8.0 

type Mode uint32

Mode is an opaque type representing a file mode. It is guaranteed to be convertable to a uint32 value. On POSIX sytems, it is the raw underlying file mode from the Stat_t structure (as opposed to the os package's FileMode implementation).

func ParseMode added in v0.8.0 

func ParseMode(value string, mask Mode) (Mode, error)

ParseMode parses a user-specified octal string and verifies that it is limited to the bits specified in mask. It allows, but does not require, the string to begin with a 0 (or several 0s). The provided string must not be empty.

func (*Mode) UnmarshalText added in v0.8.0 

func (m *Mode) UnmarshalText(textBytes []byte) error

UnmarshalText implements the text unmarshalling interface used when loading from TOML files.

type Opener added in v0.8.0 

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

Opener is a utility type that wraps a provided root path and provides file opening operations on paths relative to that root, guaranteeing that the open operations are performed in a race-free manner that can't escape the root via a path or symbolic link. It accomplishes this by maintaining an internal stack of Directory objects which provide this race-free opening property. This implementation means that the Opener operates "fast" if it is used to open paths in a sequence that mimics depth-first traversal ordering.

func NewOpener added in v0.8.0 

func NewOpener(root string) *Opener

NewOpener creates a new Opener for the specified root path.

func (*Opener) Close added in v0.8.0 

func (o *Opener) Close() error

Close closes any open resources held by the opener. It should only be called once. Even on error, there is no benefit in calling it twice.

func (*Opener) Open added in v0.8.0 

func (o *Opener) Open(path string) (ReadableFile, error)

Open opens the file at the specified path (relative to the root). On all platforms, the path must be provided using a forward slash as the path separator, and path components must not be "." or "..". The path may be empty to open the root path itself (if it's a file). If any symbolic links or non-directory parent components are encountered, or if the target does not represent a file, this method will fail.

type OwnershipIdentifierKind added in v0.8.0 

type OwnershipIdentifierKind uint8

OwnershipIdentifierKind specifies the type of an identifier provided for ownership specification. 

const (
	// OwnershipIdentifierKindInvalid specifies an invalid identifier kind.
	OwnershipIdentifierKindInvalid OwnershipIdentifierKind = iota
	// OwnershipIdentifierKindPOSIXID specifies a POSIX user or group ID.
	OwnershipIdentifierKindPOSIXID
	// OwnershipIdentifierKindWindowsSID specifies a Windows SID.
	OwnershipIdentifierKindWindowsSID
	// OwnershipIdentifierKindWindowsSID specifies a name-based identifier.
	OwnershipIdentifierKindName
)

func ParseOwnershipIdentifier added in v0.8.0 

func ParseOwnershipIdentifier(specification string) (OwnershipIdentifierKind, string)

ParseOwnershipIdentifier parses an identifier provided for ownership specification.

type OwnershipSpecification added in v0.8.0 

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

OwnershipSpecification is an opaque type that encodes specification of file and/or directory ownership.

func NewOwnershipSpecification added in v0.8.0 

func NewOwnershipSpecification(owner, group string) (*OwnershipSpecification, error)

NewOwnershipSpecification parsers owner and group specifications and resolves their system-level identifiers.

type ProbeMode 

type ProbeMode int32

ProbeMode specifies the mode for filesystem probing. 

const (
	// ProbeMode_ProbeModeDefault represents an unspecified probe mode. It
	// should be converted to one of the following values based on the desired
	// default behavior.
	ProbeMode_ProbeModeDefault ProbeMode = 0
	// ProbeMode_ProbeModeProbe specifies that filesystem behavior should be
	// probed using temporary files to determine behavior. On some platforms,
	// especially Windows, where behavior is well-known, this flag results in
	// the same behavior as ProbeMode_ProbeModeAssume.
	ProbeMode_ProbeModeProbe ProbeMode = 1
	// ProbeMode_ProbeModeAssume specifies that filesystem behavior should be
	// assumed based on the underlying platform. This is not as accurate as
	// ProbeMode_ProbeModeProbe.
	ProbeMode_ProbeModeAssume ProbeMode = 2
)

func (ProbeMode) Description 

func (m ProbeMode) Description() string

Description returns a human-readable description of a probe mode.

func (ProbeMode) EnumDescriptor 

func (ProbeMode) EnumDescriptor() ([]byte, []int)

func (ProbeMode) IsDefault 

func (m ProbeMode) IsDefault() bool

IsDefault indicates whether or not the probe mode is ProbeMode_ProbeModeDefault.

func (ProbeMode) String 

func (x ProbeMode) String() string

func (ProbeMode) Supported 

func (m ProbeMode) Supported() bool

Supported indicates whether or not a particular probe mode is a valid, non-default value.

func (*ProbeMode) UnmarshalText 

func (m *ProbeMode) UnmarshalText(textBytes []byte) error

UnmarshalText implements the text unmarshalling interface used when loading from TOML files.

type ReadableFile added in v0.8.0 

type ReadableFile interface {
	io.Reader
	io.Seeker
	io.Closer
}

ReadableFile is a union of io.Reader, io.Seeker, and io.Closer.

type WatchMode 

type WatchMode int32

WatchMode specifies the mode for filesystem watching. 

const (
	// WatchMode_WatchModeDefault represents an unspecified watch mode. It
	// should be converted to one of the following values based on the desired
	// default behavior.
	WatchMode_WatchModeDefault WatchMode = 0
	// WatchMode_WatchModePortable specifies that native recursive watching
	// should be used to monitor paths on systems that support it if those paths
	// fall under the home directory. In these cases, a watch on the entire home
	// directory is established and filtered for events pertaining to the
	// specified path. On all other systems and for all other paths, poll-based
	// watching is used.
	WatchMode_WatchModePortable WatchMode = 1
	// WatchMode_WatchModeForcePoll specifies that only poll-based watching
	// should be used.
	WatchMode_WatchModeForcePoll WatchMode = 2
	// WatchMode_WatchModeNoWatch specifies that no watching should be used
	// (i.e. no events should be generated).
	WatchMode_WatchModeNoWatch WatchMode = 3
)

func (WatchMode) Description 

func (m WatchMode) Description() string

Description returns a human-readable description of a watch mode.

func (WatchMode) EnumDescriptor 

func (WatchMode) EnumDescriptor() ([]byte, []int)

func (WatchMode) IsDefault added in v0.8.0 

func (m WatchMode) IsDefault() bool

IsDefault indicates whether or not the watch mode is WatchMode_WatchModeDefault.

func (WatchMode) String 

func (x WatchMode) String() string

func (WatchMode) Supported 

func (m WatchMode) Supported() bool

Supported indicates whether or not a particular watch mode is a valid, non-default value.

func (*WatchMode) UnmarshalText 

func (m *WatchMode) UnmarshalText(textBytes []byte) error

UnmarshalText implements the text unmarshalling interface used when loading from TOML files.

type WritableFile added in v0.8.0 

type WritableFile interface {
	io.Writer
	io.Closer
}

WritableFile is a union of io.Writer and io.Closer.

Source Files

View all Source files

Directories

Path Synopsis
Package winfsnotify allows the user to receive file system event notifications on Windows.
 Package winfsnotify allows the user to receive file system event notifications on Windows.

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.