fs

package
v0.0.0-...-5f319d3 Latest Latest
Warning

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

 Go to latest Published: May 9, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ModeDir        = iofs.ModeDir
	ModeAppend     = iofs.ModeAppend
	ModeExclusive  = iofs.ModeExclusive
	ModeTemporary  = iofs.ModeTemporary
	ModeSymlink    = iofs.ModeSymlink
	ModeDevice     = iofs.ModeDevice
	ModeNamedPipe  = iofs.ModeNamedPipe
	ModeSocket     = iofs.ModeSocket
	ModeSetuid     = iofs.ModeSetuid
	ModeSetgid     = iofs.ModeSetgid
	ModeCharDevice = iofs.ModeCharDevice
	ModeSticky     = iofs.ModeSticky
	ModeIrregular  = iofs.ModeIrregular
	ModeType       = iofs.ModeType
	ModePerm       = iofs.ModePerm
)

Variables

View Source 
var (
	// NoFollowContextKey is the context key for the no-follow flag.
	NoFollowContextKey = &contextKey{"no-follow"}
	// OriginContextKey is the context key for the originating filesystem.
	OriginContextKey = &contextKey{"origin"}
	// FilepathContextKey is the context key for the fully qualified path relative to the origin.
	FilepathContextKey = &contextKey{"filepath"}
	// ReadOnlyContextKey is the context key for the read-only flag.
	ReadOnlyContextKey = &contextKey{"read-only"}

	OpContextKey = &contextKey{"op"}
)
View Source 
var (
	// new errors
	ErrNotSupported = errors.New("operation not supported")
	ErrNotEmpty     = errors.New("directory not empty")
)
View Source 
var (
	ErrInvalid    = iofs.ErrInvalid
	ErrPermission = iofs.ErrPermission
	ErrExist      = iofs.ErrExist
	ErrNotExist   = iofs.ErrNotExist
	ErrClosed     = iofs.ErrClosed

	SkipAll = iofs.SkipAll
	SkipDir = iofs.SkipDir
)
View Source 
var (
	FormatDirEntry     = iofs.FormatDirEntry
	FormatFileInfo     = iofs.FormatFileInfo
	Glob               = iofs.Glob
	ReadFile           = iofs.ReadFile
	ValidPath          = iofs.ValidPath
	WalkDir            = iofs.WalkDir
	FileInfoToDirEntry = iofs.FileInfoToDirEntry
	ReadDir            = iofs.ReadDir
)

Functions

func AppendFile 

func AppendFile(fsys FS, filename string, data []byte) error

deprecated? this doesnt always work because Open does not support O_APPEND

func Chmod 

func Chmod(fsys FS, name string, mode FileMode) error

Chmod changes the mode of the named file if supported.

func Chown 

func Chown(fsys FS, name string, uid, gid int) error

Chown changes the numeric uid and gid of the named file if supported.

func Chtimes 

func Chtimes(fsys FS, name string, atime time.Time, mtime time.Time) error

Chtimes changes the access and modification times of the named file if supported.

func ContextFor 

func ContextFor(fsys FS) context.Context

func CopyAll 

func CopyAll(fsys FS, src, dst string) error

CopyAll recursively copies the file, directory or symbolic link at src to dst. The destination must not exist. Symbolic links are not followed.

If the copy fails half way through, the destination might be left partially written.

func CopyFS 

func CopyFS(srcFS FS, srcPath string, dstFS FS, dstPath string) error

func CopyNewFS 

func CopyNewFS(srcFS FS, srcPath string, dstFS FS, dstPath string) error

CopyNewFS copies from srcFS/srcPath to dstFS/dstPath, overwriting files if src is newer.

func DirExists 

func DirExists(fsys FS, path string) (bool, error)

func Equal 

func Equal(a, b FS) bool

func Exists 

func Exists(fsys FS, path string) (bool, error)
func FollowSymlinks(ctx context.Context) bool

FollowSymlinks returns true if symlinks should be followed and is intended to be used on contexts passed to OpenContext, et al.

func GetXattr 

func GetXattr(ctx context.Context, fsys FS, name string, attr string) ([]byte, error)

func IsDir 

func IsDir(fsys FS, path string) (bool, error)

func IsEmpty 

func IsEmpty(fsys FS, path string) (bool, error)

func IsReadOnly 

func IsReadOnly(ctx context.Context) bool

IsReadOnly returns true if the context is read-only. 

func IsSymlink(mode FileMode) bool

func ListXattrs 

func ListXattrs(ctx context.Context, fsys FS, name string) ([]string, error)

func Mkdir 

func Mkdir(fsys FS, name string, perm FileMode) error

Mkdir creates a directory with the given permissions if supported.

func MkdirAll 

func MkdirAll(fsys FS, name string, perm FileMode) error

MkdirAll creates a directory and any necessary parents with the given permissions if supported.

func Op 

func Op(ctx context.Context) string

Op returns the operation for the given context. TODO: this and other origin stuff should be a struct in a single context value.

func ReadAt 

func ReadAt(f File, p []byte, off int64) (int, error)

ReadAt reads len(p) bytes into p starting at offset off in the file f. If f does not support ReadAt or Seek, it reads and discards bytes until the offset. 

func Readlink(fsys FS, name string) (string, error)

func Remove 

func Remove(fsys FS, name string) error

Remove removes the named file or empty directory if supported.

func RemoveAll 

func RemoveAll(fsys FS, name string) error

RemoveAll removes path name and any children it contains if supported.

func RemoveXattr 

func RemoveXattr(ctx context.Context, fsys FS, name string, attr string) error

func Rename 

func Rename(fsys FS, oldname, newname string) error

Rename renames (moves) oldname to newname if supported.

func ResolveTo 

func ResolveTo[T FS](fsys FS, ctx context.Context, name string) (T, string, error)

ResolveTo resolves the name to an FS extension type if possible. It uses ResolveFS if available, otherwise it falls back to SubFS.

func SameFile 

func SameFile(a, b File) bool

func Seek 

func Seek(f File, offset int64, whence int) (int64, error)

Seek seeks to the given offset and whence.

func SetXattr 

func SetXattr(ctx context.Context, fsys FS, name string, attr string, data []byte, flags int) error
func Symlink(fsys FS, oldname, newname string) error

func Sync 

func Sync(f File) error

func TempDir 

func TempDir(fsys FS, dir, prefix string) (name string, err error)

func Truncate 

func Truncate(fsys FS, name string, size int64) error

func Watch 

func Watch(fsys FS, ctx context.Context, name string, exclude ...string) (<-chan Event, error)

- use context to cancel watch - if context is done, return a closed channel - name can end with /... for recursive watch - exclude can be a glob pattern

func WithFilepath 

func WithFilepath(ctx context.Context, filepath string) context.Context

WithFilepath returns a new context with the FilepathContextKey set to the given filepath unless there is already a filepath in the context.

func WithNoFollow 

func WithNoFollow(ctx context.Context) context.Context

WithNoFollow returns a new context with the NoFollowContextKey set to true.

func WithOp 

func WithOp(ctx context.Context, op string) context.Context

func WithOrigin 

func WithOrigin(ctx context.Context, fsys FS, name string, op string) context.Context

WithOrigin returns a new context with the OriginContextKey set to the given filesystem unless there is already an origin filesystem in the context.

func WithReadOnly 

func WithReadOnly(ctx context.Context) context.Context

WithReadOnly returns a new context with the ReadOnlyContextKey set to true.

func Write 

func Write(f File, data []byte) (int, error)

Write writes data to the file.

func WriteAt 

func WriteAt(f File, data []byte, off int64) (n int, err error)

WriteAt writes data to the file at the given offset.

func WriteFile 

func WriteFile(fsys FS, filename string, data []byte, perm FileMode) error

Types

type ChmodFS 

type ChmodFS interface {
	FS
	Chmod(name string, mode FileMode) error
}

type ChownFS 

type ChownFS interface {
	FS
	Chown(name string, uid, gid int) error
}

type ChtimesFS 

type ChtimesFS interface {
	FS
	Chtimes(name string, atime time.Time, mtime time.Time) error
}

type CreateFS 

type CreateFS interface {
	FS
	Create(name string) (File, error)
}

type DefaultFS 

type DefaultFS struct {
	fs.FS
}

DefaultFS wraps an fs.FS and implements all extended filesystem interfaces (MkdirFS, RemoveFS, RenameFS, etc.) by delegating to the corresponding package-level functions.

This is useful when embedding a filesystem in a new struct that only needs to override specific methods. Normally, if you embed an fs.FS interface in a struct, type assertions for extended interfaces will fail even if the underlying filesystem implements them. By wrapping with DefaultFS first, the wrapper struct gains implementations of all extended interfaces that properly delegate to the wrapped filesystem.

Example: 

type myFS struct {
    *fs.DefaultFS
}

func (m *myFS) Open(name string) (fs.File, error) {
    // custom Open implementation
}

// Create wrapper - Mkdir, Remove, etc. will reach originalFS
wrapped := &myFS{DefaultFS: fs.NewDefault(originalFS)}

func NewDefault 

func NewDefault(fsys fs.FS) *DefaultFS

NewDefault wraps an fs.FS with DefaultFS to enable interface passthrough.

func (*DefaultFS) Chmod 

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

func (*DefaultFS) Chown 

func (f *DefaultFS) Chown(name string, uid, gid int) error

func (*DefaultFS) Chtimes 

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

func (*DefaultFS) Create 

func (f *DefaultFS) Create(name string) (File, error)

func (*DefaultFS) GetXattr 

func (f *DefaultFS) GetXattr(ctx context.Context, name string, attr string) ([]byte, error)

func (*DefaultFS) ListXattrs 

func (f *DefaultFS) ListXattrs(ctx context.Context, name string) ([]string, error)

func (*DefaultFS) Lstat 

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

func (*DefaultFS) LstatContext 

func (f *DefaultFS) LstatContext(ctx context.Context, name string) (FileInfo, error)

func (*DefaultFS) Mkdir 

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

func (*DefaultFS) MkdirAll 

func (f *DefaultFS) MkdirAll(name string, perm FileMode) error

func (*DefaultFS) OpenContext 

func (f *DefaultFS) OpenContext(ctx context.Context, name string) (File, error)

func (*DefaultFS) OpenFile 

func (f *DefaultFS) OpenFile(name string, flag int, perm FileMode) (File, error)

func (*DefaultFS) ReadDirContext 

func (f *DefaultFS) ReadDirContext(ctx context.Context, name string) ([]DirEntry, error)
func (f *DefaultFS) Readlink(name string) (string, error)

func (*DefaultFS) Remove 

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

func (*DefaultFS) RemoveAll 

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

func (*DefaultFS) RemoveXattr 

func (f *DefaultFS) RemoveXattr(ctx context.Context, name string, attr string) error

func (*DefaultFS) Rename 

func (f *DefaultFS) Rename(oldname, newname string) error

func (*DefaultFS) SetXattr 

func (f *DefaultFS) SetXattr(ctx context.Context, name string, attr string, data []byte, flags int) error

func (*DefaultFS) Stat 

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

func (*DefaultFS) StatContext 

func (f *DefaultFS) StatContext(ctx context.Context, name string) (FileInfo, error)

func (*DefaultFS) Sub 

func (f *DefaultFS) Sub(dir string) (FS, error)
func (f *DefaultFS) Symlink(oldname, newname string) error

func (*DefaultFS) Truncate 

func (f *DefaultFS) Truncate(name string, size int64) error

func (*DefaultFS) Watch 

func (f *DefaultFS) Watch(ctx context.Context, name string, exclude ...string) (<-chan Event, error)

func (*DefaultFS) WriteFile 

func (f *DefaultFS) WriteFile(name string, data []byte, perm FileMode) error

type DefaultFile 

type DefaultFile struct {
	fs.File
}

DefaultFile wraps an fs.File and implements extended file interfaces (io.Writer, io.ReaderAt, io.WriterAt, io.Seeker, SyncFile) by delegating to the corresponding package-level functions.

Similar to DefaultFS, this allows embedding a file in a new struct while preserving access to the wrapped file's capabilities through type assertions.

func (DefaultFile) ReadAt 

func (f DefaultFile) ReadAt(p []byte, off int64) (int, error)

func (DefaultFile) Seek 

func (f DefaultFile) Seek(offset int64, whence int) (int64, error)

func (DefaultFile) Sync 

func (f DefaultFile) Sync() error

func (DefaultFile) Write 

func (f DefaultFile) Write(p []byte) (int, error)

func (DefaultFile) WriteAt 

func (f DefaultFile) WriteAt(p []byte, off int64) (int, error)

type DirEntry 

type DirEntry = iofs.DirEntry

func ReadDirContext 

func ReadDirContext(ctx context.Context, fsys FS, name string) ([]DirEntry, error)

TODO: change to ReadDirContext(FS, Context, string)

type Event 

type Event struct {
	Path string
	Op   string
	Err  error
}

type FS 

type FS = iofs.FS

func Origin 

func Origin(ctx context.Context) (FS, string, bool)

Origin returns the origin filesystem and filepath for the given context. The filepath may be empty but as long as there is an origin it will return true.

func Resolve 

func Resolve(fsys FS, ctx context.Context, name string) (rfsys FS, rname string, err error)

Resolve resolves to the FS directly containing the name returning that resolved FS and the relative name for that FS. It uses ResolveFS if available, otherwise it falls back to SubFS. If unable to resolve, it returns the original FS and the original name, but it can also return a PathError if .

func Sub 

func Sub(fsys FS, dir string) (FS, error)

Sub returns an FS corresponding to the subtree rooted at fsys's dir.

If dir is ".", Sub returns fsys unchanged. Otherwise, if fs implements SubFS, Sub returns fsys.Sub(dir). Otherwise, Sub returns a new FS implementation sub that, in effect, implements sub.Open(name) as fsys.Open(path.Join(dir, name)). The implementation also translates calls to ReadDir, ReadFile, and Glob appropriately.

Note that Sub(os.DirFS("/"), "prefix") is equivalent to os.DirFS("/prefix") and that neither of them guarantees to avoid operating system accesses outside "/prefix", because the implementation of os.DirFS does not check for symbolic links inside "/prefix" that point to other directories. That is, os.DirFS is not a general substitute for a chroot-style security mechanism, and Sub does not change that fact.

type File 

type File = iofs.File

func Create 

func Create(fsys FS, name string) (File, error)

Create creates or truncates the named file if supported.

func OpenContext 

func OpenContext(ctx context.Context, fsys FS, name string) (File, error)

OpenContext is a helper that opens a file with the given context and name falling back to Open if context is not supported. TODO: change to OpenContext(FS, Context, string)

func OpenFile 

func OpenFile(fsys FS, name string, flag int, perm FileMode) (f File, err error)

OpenFile is a helper that opens a file with the given flag and permissions if supported.

type FileInfo 

type FileInfo = iofs.FileInfo

func Lstat 

func Lstat(fsys FS, name string) (FileInfo, error)

func LstatContext 

func LstatContext(ctx context.Context, fsys FS, name string) (FileInfo, error)

TODO: change to StatContext(FS, Context, string)

func Stat 

func Stat(fsys FS, name string) (FileInfo, error)

func StatContext 

func StatContext(ctx context.Context, fsys FS, name string) (FileInfo, error)

TODO: change to StatContext(FS, Context, string)

type FileMode 

type FileMode = iofs.FileMode

type GlobFS 

type GlobFS = iofs.GlobFS

type ID 

type ID struct {
	Dev uint64
	Ino uint64
	Ptr uint64
	Sum uint64
}

func Identity 

func Identity(f any) ID

type IdentityFile 

type IdentityFile interface {
	File
	Identity() ID
}

type MkdirAllFS 

type MkdirAllFS interface {
	FS
	MkdirAll(path string, perm FileMode) error
}

type MkdirFS 

type MkdirFS interface {
	FS
	Mkdir(name string, perm FileMode) error
}

type Namer 

type Namer interface {
	Name() string
}

type OpenContextFS 

type OpenContextFS interface {
	FS
	OpenContext(ctx context.Context, name string) (File, error)
}

type OpenFileFS 

type OpenFileFS interface {
	FS
	OpenFile(name string, flag int, perm FileMode) (File, error)
}

type PathError 

type PathError = iofs.PathError

type ReadDirContextFS 

type ReadDirContextFS interface {
	FS
	ReadDirContext(ctx context.Context, name string) ([]DirEntry, error)
}

type ReadDirFS 

type ReadDirFS = iofs.ReadDirFS

type ReadDirFile 

type ReadDirFile = iofs.ReadDirFile

type ReadFileFS 

type ReadFileFS = iofs.ReadFileFS

type ReadlinkFS 

type ReadlinkFS interface {
	FS
	Readlink(name string) (string, error)
}

type RemoveAllFS 

type RemoveAllFS interface {
	FS
	RemoveAll(path string) error
}

type RemoveFS 

type RemoveFS interface {
	FS
	Remove(name string) error
}

type RenameFS 

type RenameFS interface {
	FS
	Rename(oldname, newname string) error
}

type ResolveFS 

type ResolveFS interface {
	FS
	ResolveFS(ctx context.Context, name string) (FS, string, error)
}

type StatContextFS 

type StatContextFS interface {
	FS
	StatContext(ctx context.Context, name string) (FileInfo, error)
}

type StatFS 

type StatFS = iofs.StatFS

type SubFS 

type SubFS = iofs.SubFS

type SubdirFS 

type SubdirFS struct {
	Fsys FS
	Dir  string
}

func (*SubdirFS) Chmod 

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

func (*SubdirFS) Chtimes 

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

func (*SubdirFS) Create 

func (f *SubdirFS) Create(name string) (File, error)

func (*SubdirFS) GetXattr 

func (f *SubdirFS) GetXattr(ctx context.Context, name string, attr string) ([]byte, error)

func (*SubdirFS) ListXattrs 

func (f *SubdirFS) ListXattrs(ctx context.Context, name string) ([]string, error)

func (*SubdirFS) Mkdir 

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

func (*SubdirFS) Open 

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

func (*SubdirFS) OpenContext 

func (f *SubdirFS) OpenContext(ctx context.Context, name string) (File, error)
func (f *SubdirFS) Readlink(name string) (string, error)

func (*SubdirFS) Remove 

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

func (*SubdirFS) RemoveXattr 

func (f *SubdirFS) RemoveXattr(ctx context.Context, name string, attr string) error

func (*SubdirFS) Rename 

func (f *SubdirFS) Rename(oldname string, newname string) error

func (*SubdirFS) SetXattr 

func (f *SubdirFS) SetXattr(ctx context.Context, name string, attr string, data []byte, flags int) error

func (*SubdirFS) Stat 

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

func (*SubdirFS) StatContext 

func (f *SubdirFS) StatContext(ctx context.Context, name string) (FileInfo, error)

func (*SubdirFS) Sub 

func (f *SubdirFS) Sub(dir string) (FS, error)
func (f *SubdirFS) Symlink(oldname string, newname string) error

func (*SubdirFS) Truncate 

func (f *SubdirFS) Truncate(name string, size int64) error

type SymlinkFS 

type SymlinkFS interface {
	FS
	Symlink(oldname, newname string) error
}

type SyncFile 

type SyncFile interface {
	File
	Sync() error
}

type TruncateFS 

type TruncateFS interface {
	FS
	Truncate(name string, size int64) error
}

type WalkDirFunc 

type WalkDirFunc = iofs.WalkDirFunc

type WatchFS 

type WatchFS interface {
	FS
	Watch(ctx context.Context, name string, exclude ...string) (<-chan Event, error)
}

type WriteFileFS 

type WriteFileFS interface {
	FS
	WriteFile(filename string, data []byte, perm FileMode) error
}

type XattrFS 

type XattrFS interface {
	FS
	SetXattr(ctx context.Context, name string, attr string, data []byte, flags int) error
	GetXattr(ctx context.Context, name string, attr string) ([]byte, error)
	ListXattrs(ctx context.Context, name string) ([]string, error)
	RemoveXattr(ctx context.Context, name string, attr string) error
}

Source Files

View all Source files

Directories

Path Synopsis
Package cowfs implements a copy-on-write filesystem that combines a read-only base filesystem with a writable overlay filesystem.
 Package cowfs implements a copy-on-write filesystem that combines a read-only base filesystem with a writable overlay filesystem.
fstest command
net
tcp
tarfs implements a read-only in-memory representation of a tar archive
 tarfs implements a read-only in-memory representation of a tar archive

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.