filesystem

package
v0.9.2 Latest Latest
Warning

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

 Go to latest Published: Jul 17, 2019 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package filesystem provides low-level race-free traversal mechanisms and modification operations for filesystems.

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 data directory inside the
	// user's home directory.
	MutagenDirectoryName = ".mutagen"

	// MutagenDaemonDirectoryName is the name of the daemon subdirectory within
	// the Mutagen data directory.
	MutagenDaemonDirectoryName = "daemon"

	// MutagenAgentsDirectoryName is the subdirectory of the Mutagen directory
	// in which agents should be stored.
	MutagenAgentsDirectoryName = "agents"

	// MutagenSessionsDirectoryName is the name of the sessions subdirectory
	// within the Mutagen data directory.
	MutagenSessionsDirectoryName = "sessions"

	// MutagenCachesDirectoryName is the name of the caches subdirectory within
	// the Mutagen data directory.
	MutagenCachesDirectoryName = "caches"

	// MutagenArchivesDirectoryName is the name of the archives subdirectory
	// within the Mutagen data directory.
	MutagenArchivesDirectoryName = "archives"

	// MutagenStagingDirectoryName is the name of the staging subdirectory
	// within the Mutagen data directory.
	MutagenStagingDirectoryName = "staging"
)
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.

Functions

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 MarkHidden added in v0.9.0 

func MarkHidden(path string) error

MarkHidden ensures that a path is hidden.

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 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 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) Descriptor added in v0.9.0 

func (d *Directory) Descriptor() int

Descriptor provides access to the raw file descriptor underlying the directory. It should not be used or retained beyond the point in time where the Close method is called, and it should not be closed externally. Its usefulness is to code which relies on file-descriptor-based operations. This method does not exist on Windows systems, so it should only be used in POSIX-specific code.

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. On POSIX systems, the directory itself can be re-opened (with a different underlying file handle pointing to the same directory) by passing "." to this function.

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 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 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 (*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. It requires that the specified mode bits lie within ModePermissionsMask, otherwise an error is returned. If an error is returned, the mode is unmodified.

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 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 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 behavior provides filesystem behavior probing facilities.
 Package behavior provides filesystem behavior probing facilities.
internal/format
Package format provides filesystem format enumerations and querying functions.
 Package format provides filesystem format enumerations and querying functions.
internal
syscall
Package syscall is an internal POSIX system call compatibility shim needed to ensure the availability of certain constants and functions across all supported POSIX platforms.
 Package syscall is an internal POSIX system call compatibility shim needed to ensure the availability of certain constants and functions across all supported POSIX platforms.
third_party/os
Package locking provides a file locking type that is robust to abrupt process termination.
 Package locking provides a file locking type that is robust to abrupt process termination.
Package watching provides a uniform interface to native filesystem watching facilities.
 Package watching provides a uniform interface to native filesystem watching facilities.
internal/third_party/notify
internal/third_party/winfsnotify
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.