fs

package
v1.27.11-rc.1 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2024 License: MPL-2.0 Imports: 38 Imported by: 4

Documentation

Index

Constants

View Source 
const (
	ModePerm      = FileMode(os.ModePerm)
	ModeSetgid    = FileMode(os.ModeSetgid)
	ModeSetuid    = FileMode(os.ModeSetuid)
	ModeSticky    = FileMode(os.ModeSticky)
	ModeSymlink   = FileMode(os.ModeSymlink)
	ModeType      = FileMode(os.ModeType)
	PathSeparator = os.PathSeparator
	OptAppend     = os.O_APPEND
	OptCreate     = os.O_CREATE
	OptExclusive  = os.O_EXCL
	OptReadOnly   = os.O_RDONLY
	OptReadWrite  = os.O_RDWR
	OptSync       = os.O_SYNC
	OptTruncate   = os.O_TRUNC
	OptWriteOnly  = os.O_WRONLY
)
View Source 
const (
	WindowsTempPrefix = "~syncthing~"
	UnixTempPrefix    = ".syncthing."
)
View Source 
const WatchKqueue = false

WatchKqueue indicates if kqueue is used for filesystem watching

Variables

View Source 
var (
	ErrWatchNotSupported  = errors.New("watching is not supported")
	ErrXattrsNotSupported = errors.New("extended attributes are not supported on this platform")
)
View Source 
var CopyRangeMethod_name = map[int32]string{
	0: "COPY_RANGE_METHOD_STANDARD",
	1: "COPY_RANGE_METHOD_IOCTL",
	2: "COPY_RANGE_METHOD_COPY_FILE_RANGE",
	3: "COPY_RANGE_METHOD_SEND_FILE",
	4: "COPY_RANGE_METHOD_DUPLICATE_EXTENTS",
	5: "COPY_RANGE_METHOD_ALL_WITH_FALLBACK",
}
View Source 
var CopyRangeMethod_value = map[string]int32{
	"COPY_RANGE_METHOD_STANDARD":          0,
	"COPY_RANGE_METHOD_IOCTL":             1,
	"COPY_RANGE_METHOD_COPY_FILE_RANGE":   2,
	"COPY_RANGE_METHOD_SEND_FILE":         3,
	"COPY_RANGE_METHOD_DUPLICATE_EXTENTS": 4,
	"COPY_RANGE_METHOD_ALL_WITH_FALLBACK": 5,
}
View Source 
var ErrExist = fs.ErrExist

ErrExist is the equivalent of os.ErrExist

View Source 
var ErrInfiniteRecursion = errors.New("infinite filesystem recursion detected")
View Source 
var ErrNotExist = fs.ErrNotExist

ErrNotExist is the equivalent of os.ErrNotExist

View Source 
var FilesystemType_name = map[int32]string{
	0: "FILESYSTEM_TYPE_BASIC",
	1: "FILESYSTEM_TYPE_FAKE",
}
View Source 
var FilesystemType_value = map[string]int32{
	"FILESYSTEM_TYPE_BASIC": 0,
	"FILESYSTEM_TYPE_FAKE":  1,
}
View Source 
var IsPathSeparator = os.IsPathSeparator

IsPathSeparator is the equivalent of os.IsPathSeparator

View Source 
var SkipDir = filepath.SkipDir

SkipDir is used as a return value from WalkFuncs to indicate that the directory named in the call is to be skipped. It is not returned as an error by any function.

Functions

func Canonicalize added in v0.14.46 

func Canonicalize(file string) (string, error)

Canonicalize checks that the file path is valid and returns it in the "canonical" form: - /foo/bar -> foo/bar - / -> "."

func CommonPrefix added in v1.1.4 

func CommonPrefix(first, second string) string

func CopyRange added in v1.8.0 

func CopyRange(copyMethod CopyRangeMethod, src, dst File, srcOffset, dstOffset, size int64) error

CopyRange tries to use the specified method to copy data between two files. Takes size bytes at offset srcOffset from the source file, and copies the data to destination file at offset dstOffset. If required, adjusts the size of the destination file to fit that much data.

On Linux/BSD you can ask it to use ioctl and copy_file_range system calls, which if the underlying filesystem supports it tries referencing existing data in the source file, instead of making a copy and taking up additional space.

CopyRange does its best to have no effect on src and dst file offsets (copy operation should not affect it).

func ExpandTilde added in v0.14.37 

func ExpandTilde(path string) (string, error)

func IsErrCaseConflict added in v1.9.0 

func IsErrCaseConflict(err error) bool

func IsExist added in v0.14.27 

func IsExist(err error) bool

func IsInternal added in v0.14.38 

func IsInternal(file string) bool

IsInternal returns true if the file, as a path relative to the folder root, represents an internal file that should always be ignored. The file path must be clean (i.e., in canonical shortest form).

func IsNotExist added in v0.14.27 

func IsNotExist(err error) bool

IsNotExist is the equivalent of os.IsNotExist

func IsParent added in v1.0.0 

func IsParent(path, parent string) bool

IsParent compares paths purely lexicographically, meaning it returns false if path and parent aren't both absolute or relative.

func IsPermission added in v0.14.37 

func IsPermission(err error) bool

IsPermission is the equivalent of os.IsPermission

func IsTemporary added in v0.14.38 

func IsTemporary(name string) bool

IsTemporary is true if the file name has the temporary prefix. Regardless of the normally used prefix, the standard Windows and Unix temp prefixes are always recognized as temp files.

func PathComponents added in v1.16.0 

func PathComponents(path string) []string

PathComponents returns a list of names of parent directories and the leaf item for the given native (fs.PathSeparator delimited) and clean path.

func SanitizePath added in v1.12.1 

func SanitizePath(path string) string

SanitizePath takes a string that might contain all kinds of special characters and makes a valid, similar, path name out of it.

Spans of invalid characters, whitespace and/or non-UTF-8 sequences are replaced by a single space. The result is always UTF-8 and contains only printable characters, as determined by unicode.IsPrint.

Invalid characters are non-printing runes, things not allowed in file names in Windows, and common shell metacharacters. Even if asterisks and pipes and stuff are allowed on Unixes in general they might not be allowed by the filesystem and may surprise the user and cause shell oddness. This function is intended for file names we generate on behalf of the user, and surprising them with odd shell characters in file names is unkind.

We include whitespace in the invalid characters so that multiple whitespace is collapsed to a single space. Additionally, whitespace at either end is removed.

If the result is a name disallowed on windows, a hyphen is prepended.

func TempName added in v0.14.38 

func TempName(name string) string

func TempNameWithPrefix added in v0.14.44 

func TempNameWithPrefix(name, prefix string) string

func UnicodeLowercaseNormalized added in v1.17.0 

func UnicodeLowercaseNormalized(s string) string

UnicodeLowercaseNormalized returns the Unicode lower case variant of s, having also normalized it to normalization form C.

func WindowsInvalidFilename added in v0.14.41 

func WindowsInvalidFilename(name string) error

func WriteFile added in v1.23.5 

func WriteFile(fs Filesystem, name string, data []byte, perm FileMode) error

WriteFile writes data to the named file, creating it if necessary. If the file does not exist, WriteFile creates it with permissions perm (before umask); otherwise WriteFile truncates it before writing, without changing permissions. Since Writefile requires multiple system calls to complete, a failure mid-operation can leave the file in a partially written state.

Types

type BasicFilesystem added in v0.14.13 

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

The BasicFilesystem implements all aspects by delegating to package os. All paths are relative to the root and cannot (should not) escape the root directory.

func (*BasicFilesystem) Chmod added in v0.14.13 

func (f *BasicFilesystem) Chmod(name string, mode FileMode) error

func (*BasicFilesystem) Chtimes added in v0.14.13 

func (f *BasicFilesystem) Chtimes(name string, atime time.Time, mtime time.Time) error

func (*BasicFilesystem) Create added in v0.14.13 

func (f *BasicFilesystem) Create(name string) (File, error)
func (f *BasicFilesystem) CreateSymlink(target, name string) error

func (*BasicFilesystem) DirNames added in v0.14.13 

func (f *BasicFilesystem) DirNames(name string) ([]string, error)

func (*BasicFilesystem) GetXattr added in v1.22.0 

func (f *BasicFilesystem) GetXattr(path string, xattrFilter XattrFilter) ([]protocol.Xattr, error)

func (*BasicFilesystem) Glob added in v0.14.37 

func (f *BasicFilesystem) Glob(pattern string) ([]string, error)

func (*BasicFilesystem) Hide added in v0.14.37 

func (f *BasicFilesystem) Hide(name string) error

Hide is a noop on unix, as hiding files requires renaming them. We still check that the relative path does not try to escape the root

func (*BasicFilesystem) Lchown added in v1.1.0 

func (f *BasicFilesystem) Lchown(name, uid, gid string) error

func (*BasicFilesystem) Lstat added in v0.14.13 

func (f *BasicFilesystem) Lstat(name string) (FileInfo, error)

func (*BasicFilesystem) Mkdir added in v0.14.13 

func (f *BasicFilesystem) Mkdir(name string, perm FileMode) error

func (*BasicFilesystem) MkdirAll added in v0.14.37 

func (f *BasicFilesystem) MkdirAll(path string, perm FileMode) error

MkdirAll creates a directory named path, along with any necessary parents, and returns nil, or else returns an error. The permission bits perm are used for all directories that MkdirAll creates. If path is already a directory, MkdirAll does nothing and returns nil.

func (*BasicFilesystem) Open added in v0.14.13 

func (f *BasicFilesystem) Open(name string) (File, error)

func (*BasicFilesystem) OpenFile added in v0.14.37 

func (f *BasicFilesystem) OpenFile(name string, flags int, mode FileMode) (File, error)

func (*BasicFilesystem) Options added in v1.15.0 

func (f *BasicFilesystem) Options() []Option

func (*BasicFilesystem) PlatformData added in v1.21.0 

func (f *BasicFilesystem) PlatformData(name string, scanOwnership, scanXattrs bool, xattrFilter XattrFilter) (protocol.PlatformData, error)
func (f *BasicFilesystem) ReadSymlink(name string) (string, error)

func (*BasicFilesystem) Remove added in v0.14.13 

func (f *BasicFilesystem) Remove(name string) error

func (*BasicFilesystem) RemoveAll added in v0.14.37 

func (f *BasicFilesystem) RemoveAll(name string) error

func (*BasicFilesystem) Rename added in v0.14.13 

func (f *BasicFilesystem) Rename(oldpath, newpath string) error

func (*BasicFilesystem) Roots added in v0.14.37 

func (*BasicFilesystem) Roots() ([]string, error)

func (*BasicFilesystem) SameFile added in v0.14.44 

func (*BasicFilesystem) SameFile(fi1, fi2 FileInfo) bool

func (*BasicFilesystem) SetXattr added in v1.22.0 

func (f *BasicFilesystem) SetXattr(path string, xattrs []protocol.Xattr, xattrFilter XattrFilter) error

func (*BasicFilesystem) Stat added in v0.14.13 

func (f *BasicFilesystem) Stat(name string) (FileInfo, error)

func (*BasicFilesystem) SymlinksSupported added in v0.14.13 

func (*BasicFilesystem) SymlinksSupported() bool

func (*BasicFilesystem) Type added in v0.14.37 

func (*BasicFilesystem) Type() FilesystemType

func (*BasicFilesystem) URI added in v0.14.37 

func (f *BasicFilesystem) URI() string

func (*BasicFilesystem) Unhide added in v0.14.37 

func (f *BasicFilesystem) Unhide(name string) error

Unhide is a noop on unix, as unhiding files requires renaming them. We still check that the relative path does not try to escape the root

func (*BasicFilesystem) Usage added in v0.14.37 

func (f *BasicFilesystem) Usage(name string) (Usage, error)

func (*BasicFilesystem) Walk added in v0.14.13 

func (*BasicFilesystem) Walk(_ string, _ WalkFunc) error

func (*BasicFilesystem) Watch added in v0.14.40 

func (f *BasicFilesystem) Watch(name string, ignore Matcher, ctx context.Context, ignorePerms bool) (<-chan Event, <-chan error, error)

type CopyRangeMethod added in v1.8.0 

type CopyRangeMethod int32
const (
	CopyRangeMethodStandard         CopyRangeMethod = 0
	CopyRangeMethodIoctl            CopyRangeMethod = 1
	CopyRangeMethodCopyFileRange    CopyRangeMethod = 2
	CopyRangeMethodSendFile         CopyRangeMethod = 3
	CopyRangeMethodDuplicateExtents CopyRangeMethod = 4
	CopyRangeMethodAllWithFallback  CopyRangeMethod = 5
)

func (CopyRangeMethod) EnumDescriptor added in v1.10.0 

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

func (CopyRangeMethod) MarshalText added in v1.8.0 

func (o CopyRangeMethod) MarshalText() ([]byte, error)

func (*CopyRangeMethod) ParseDefault added in v1.8.0 

func (o *CopyRangeMethod) ParseDefault(str string) error

func (CopyRangeMethod) String added in v1.8.0 

func (o CopyRangeMethod) String() string

func (*CopyRangeMethod) UnmarshalText added in v1.8.0 

func (o *CopyRangeMethod) UnmarshalText(bs []byte) error

type ErrCaseConflict added in v1.9.0 

type ErrCaseConflict struct {
	Given, Real string
}

func (*ErrCaseConflict) Error added in v1.9.0 

func (e *ErrCaseConflict) Error() string

type ErrWatchEventOutsideRoot added in v1.2.0 

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

func (*ErrWatchEventOutsideRoot) Error added in v1.2.0 

func (e *ErrWatchEventOutsideRoot) Error() string

type Event added in v0.14.40 

type Event struct {
	Name string
	Type EventType
}

type EventType added in v0.14.40 

type EventType int
const (
	NonRemove EventType = 1 + iota
	Remove
	Mixed // Should probably not be necessary to be used in filesystem interface implementation
)

func (EventType) Merge added in v0.14.49 

func (evType EventType) Merge(other EventType) EventType

Merge returns Mixed, except if evType and other are the same and not Mixed.

func (EventType) String added in v0.14.40 

func (evType EventType) String() string

type File added in v0.14.13 

type File interface {
	io.Closer
	io.Reader
	io.ReaderAt
	io.Seeker
	io.Writer
	io.WriterAt
	Name() string
	Truncate(size int64) error
	Stat() (FileInfo, error)
	Sync() error
}

The File interface abstracts access to a regular file, being a somewhat smaller interface than os.File

type FileInfo added in v0.14.13 

type FileInfo interface {
	// Standard things present in os.FileInfo
	Name() string
	Mode() FileMode
	Size() int64
	ModTime() time.Time
	IsDir() bool
	Sys() interface{}
	// Extensions
	IsRegular() bool
	IsSymlink() bool
	Owner() int
	Group() int
	InodeChangeTime() time.Time // may be zero if not supported
}

The FileInfo interface is almost the same as os.FileInfo, but with the Sys method removed (as we don't want to expose whatever is underlying) and with a couple of convenience methods added.

type FileMode added in v0.14.13 

type FileMode uint32

FileMode is similar to os.FileMode

func (FileMode) String added in v0.14.53 

func (fm FileMode) String() string

type Filesystem added in v0.14.13 

type Filesystem interface {
	Chmod(name string, mode FileMode) error
	Lchown(name string, uid, gid string) error // uid/gid as strings; numeric on POSIX, SID on Windows, like in os/user package
	Chtimes(name string, atime time.Time, mtime time.Time) error
	Create(name string) (File, error)
	CreateSymlink(target, name string) error
	DirNames(name string) ([]string, error)
	Lstat(name string) (FileInfo, error)
	Mkdir(name string, perm FileMode) error
	MkdirAll(name string, perm FileMode) error
	Open(name string) (File, error)
	OpenFile(name string, flags int, mode FileMode) (File, error)
	ReadSymlink(name string) (string, error)
	Remove(name string) error
	RemoveAll(name string) error
	Rename(oldname, newname string) error
	Stat(name string) (FileInfo, error)
	SymlinksSupported() bool
	Walk(name string, walkFn WalkFunc) error
	// If setup fails, returns non-nil error, and if afterwards a fatal (!)
	// error occurs, sends that error on the channel. Afterwards this watch
	// can be considered stopped.
	Watch(path string, ignore Matcher, ctx context.Context, ignorePerms bool) (<-chan Event, <-chan error, error)
	Hide(name string) error
	Unhide(name string) error
	Glob(pattern string) ([]string, error)
	Roots() ([]string, error)
	Usage(name string) (Usage, error)
	Type() FilesystemType
	URI() string
	Options() []Option
	SameFile(fi1, fi2 FileInfo) bool
	PlatformData(name string, withOwnership, withXattrs bool, xattrFilter XattrFilter) (protocol.PlatformData, error)
	GetXattr(name string, xattrFilter XattrFilter) ([]protocol.Xattr, error)
	SetXattr(path string, xattrs []protocol.Xattr, xattrFilter XattrFilter) error
	// contains filtered or unexported methods
}

The Filesystem interface abstracts access to the file system.

func NewFilesystem added in v0.14.37 

func NewFilesystem(fsType FilesystemType, uri string, opts ...Option) Filesystem

func NewWalkFilesystem added in v0.14.28 

func NewWalkFilesystem(next Filesystem) Filesystem

type FilesystemType added in v0.14.37 

type FilesystemType int32
const (
	FilesystemTypeBasic FilesystemType = 0
	FilesystemTypeFake  FilesystemType = 1
)

func (FilesystemType) EnumDescriptor added in v1.10.0 

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

func (FilesystemType) MarshalText added in v0.14.37 

func (t FilesystemType) MarshalText() ([]byte, error)

func (FilesystemType) String added in v0.14.37 

func (t FilesystemType) String() string

func (*FilesystemType) UnmarshalText added in v0.14.37 

func (t *FilesystemType) UnmarshalText(bs []byte) error

type Matcher added in v0.14.40 

type Matcher interface {
	Match(name string) ignoreresult.R
}

type MtimeFSOption added in v0.14.41 

type MtimeFSOption func(*mtimeFS)

func WithCaseInsensitivity added in v0.14.41 

func WithCaseInsensitivity(v bool) MtimeFSOption

type MtimeMapping added in v1.17.0 

type MtimeMapping struct {
	// "Real" is the on disk timestamp
	Real time.Time `json:"real"`
	// "Virtual" is what want the timestamp to be
	Virtual time.Time `json:"virtual"`
}

MtimeMapping represents the mapping as stored in the database

func GetMtimeMapping added in v1.17.0 

func GetMtimeMapping(fs Filesystem, file string) (MtimeMapping, error)

func (*MtimeMapping) Marshal added in v1.17.0 

func (t *MtimeMapping) Marshal() ([]byte, error)

func (*MtimeMapping) Unmarshal added in v1.17.0 

func (t *MtimeMapping) Unmarshal(bs []byte) error

type Option added in v1.9.0 

type Option interface {
	String() string
	// contains filtered or unexported methods
}

Option modifies a filesystem at creation. An option might be specific to a filesystem-type.

String is used to detect options with the same effect, i.e. must be different for options with different effects. Meaning if an option has parameters, a representation of those must be part of the returned string.

func NewMtimeOption added in v1.20.0 

func NewMtimeOption(db database, options ...MtimeFSOption) Option

NewMtimeOption makes any filesystem provide nanosecond mtime precision, regardless of what shenanigans the underlying filesystem gets up to.

type OptionDetectCaseConflicts added in v1.20.0 

type OptionDetectCaseConflicts struct{}

OptionDetectCaseConflicts ensures that the potentially case-insensitive filesystem behaves like a case-sensitive filesystem. Meaning that it takes into account the real casing of a path and returns ErrCaseConflict if the given path differs from the real path. It is safe to use with any filesystem, i.e. also a case-sensitive one. However it will add some overhead and thus shouldn't be used if the filesystem is known to already behave case-sensitively.

func (*OptionDetectCaseConflicts) String added in v1.20.0 

func (*OptionDetectCaseConflicts) String() string

type OptionJunctionsAsDirs added in v1.15.0 

type OptionJunctionsAsDirs struct{}

func (*OptionJunctionsAsDirs) String added in v1.15.0 

func (*OptionJunctionsAsDirs) String() string

type Usage added in v0.14.37 

type Usage struct {
	Free  uint64
	Total uint64
}

Usage represents filesystem space usage

type WalkFunc added in v0.14.13 

type WalkFunc func(path string, info FileInfo, err error) error

WalkFunc is the type of the function called for each file or directory visited by Walk. The path argument contains the argument to Walk as a prefix; that is, if Walk is called with "dir", which is a directory containing the file "a", the walk function will be called with argument "dir/a". The info argument is the FileInfo for the named path.

If there was a problem walking to the file or directory named by path, the incoming error will describe the problem and the function can decide how to handle that error (and Walk will not descend into that directory). If an error is returned, processing stops. The sole exception is when the function returns the special value SkipDir. If the function returns SkipDir when invoked on a directory, Walk skips the directory's contents entirely. If the function returns SkipDir when invoked on a non-directory file, Walk skips the remaining files in the containing directory.

type XattrFilter added in v1.22.0 

type XattrFilter interface {
	Permit(string) bool
	GetMaxSingleEntrySize() int
	GetMaxTotalSize() int
}

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.