ufs

package
v0.0.0-...-eb3c7bf Latest Latest
Warning

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

 Go to latest Published: Dec 5, 2024 License: MIT, MIT Imports: 15 Imported by: 0

README

Filesystem

Coming Soon™

TODO

Licensing

Most code in this package is licensed under MIT with some exceptions.

The following files are licensed under BSD-3-Clause due to them being copied verbatim or derived from Go's source code.

These changes are not associated with nor endorsed by The Go Authors.

Documentation

Overview

Package ufs provides an abstraction layer for performing I/O on filesystems. This package is designed to be used in-place of standard `os` package I/O calls, and is not designed to be used as a generic filesystem abstraction like the `io/fs` package.

The primary use-case of this package was to provide a "chroot-like" `os` wrapper, so we can safely sandbox I/O operations within a directory and use untrusted arbitrary paths.

Index

Constants

View Source 
const (
	// ModeDir represents a directory.
	// d: is a directory
	ModeDir = iofs.ModeDir
	// ModeAppend represents an append-only file.
	// a: append-only
	ModeAppend = iofs.ModeAppend
	// ModeExclusive represents an exclusive file.
	// l: exclusive use
	ModeExclusive = iofs.ModeExclusive
	// ModeTemporary .
	// T: temporary file; Plan 9 only.
	ModeTemporary = iofs.ModeTemporary
	// ModeSymlink .
	// L: symbolic link.
	ModeSymlink = iofs.ModeSymlink
	// ModeDevice .
	// D: device file.
	ModeDevice = iofs.ModeDevice
	// ModeNamedPipe .
	// p: named pipe (FIFO)
	ModeNamedPipe = iofs.ModeNamedPipe
	// ModeSocket .
	// S: Unix domain socket.
	ModeSocket = iofs.ModeSocket
	// ModeSetuid .
	// u: setuid
	ModeSetuid = iofs.ModeSetuid
	// ModeSetgid .
	// g: setgid
	ModeSetgid = iofs.ModeSetgid
	// ModeCharDevice .
	// c: Unix character device, when ModeDevice is set
	ModeCharDevice = iofs.ModeCharDevice
	// ModeSticky .
	// t: sticky
	ModeSticky = iofs.ModeSticky
	// ModeIrregular .
	// ?: non-regular file; nothing else is known about this file.
	ModeIrregular = iofs.ModeIrregular

	// ModeType .
	ModeType = iofs.ModeType

	// ModePerm .
	// Unix permission bits, 0o777.
	ModePerm = iofs.ModePerm
)

The defined file mode bits are the most significant bits of the FileMode. The nine least-significant bits are the standard Unix rwxrwxrwx permissions. The values of these bits should be considered part of the public API and may be used in wire protocols or disk representations: they must not be changed, although new bits might be added.

View Source 
const (
	// O_RDONLY opens the file read-only.
	O_RDONLY = unix.O_RDONLY
	// O_WRONLY opens the file write-only.
	O_WRONLY = unix.O_WRONLY
	// O_RDWR opens the file read-write.
	O_RDWR = unix.O_RDWR
	// O_APPEND appends data to the file when writing.
	O_APPEND = unix.O_APPEND
	// O_CREATE creates a new file if it doesn't exist.
	O_CREATE = unix.O_CREAT
	// O_EXCL is used with O_CREATE, file must not exist.
	O_EXCL = unix.O_EXCL
	// O_SYNC open for synchronous I/O.
	O_SYNC = unix.O_SYNC
	// O_TRUNC truncates regular writable file when opened.
	O_TRUNC = unix.O_TRUNC
	// O_DIRECTORY opens a directory only. If the entry is not a directory an
	// error will be returned.
	O_DIRECTORY = unix.O_DIRECTORY
	// O_NOFOLLOW opens the exact path given without following symlinks.
	O_NOFOLLOW  = unix.O_NOFOLLOW
	O_CLOEXEC   = unix.O_CLOEXEC
	O_LARGEFILE = unix.O_LARGEFILE
)

Re-using the same names as Go's official `unix` and `os` package do.

View Source 
const (
	AT_SYMLINK_NOFOLLOW = unix.AT_SYMLINK_NOFOLLOW
	AT_REMOVEDIR        = unix.AT_REMOVEDIR
	AT_EMPTY_PATH       = unix.AT_EMPTY_PATH
)

Variables

View Source 
var (
	// ErrIsDirectory is an error for when an operation that operates only on
	// files is given a path to a directory.
	ErrIsDirectory = errors.New("is a directory")
	// ErrNotDirectory is an error for when an operation that operates only on
	// directories is given a path to a file.
	ErrNotDirectory = errors.New("not a directory")
	// ErrBadPathResolution is an error for when a sand-boxed filesystem
	// resolves a given path to a forbidden location.
	ErrBadPathResolution = errors.New("bad path resolution")
	// ErrNotRegular is an error for when an operation that operates only on
	// regular files is passed something other than a regular file.
	ErrNotRegular = errors.New("not a regular file")

	// ErrClosed is an error for when an entry was accessed after being closed.
	ErrClosed = iofs.ErrClosed
	// ErrInvalid is an error for when an invalid argument was used.
	ErrInvalid = iofs.ErrInvalid
	// ErrExist is an error for when an entry already exists.
	ErrExist = iofs.ErrExist
	// ErrNotExist is an error for when an entry does not exist.
	ErrNotExist = iofs.ErrNotExist
	// ErrPermission is an error for when the required permissions to perform an
	// operation are missing.
	ErrPermission = iofs.ErrPermission
)
View Source 
var SkipAll = iofs.SkipAll

SkipAll is used as a return value from WalkDirFunc to indicate that all remaining files and directories are to be skipped. It is not returned as an error by any function.

View Source 
var SkipDir = iofs.SkipDir

SkipDir is used as a return value from WalkDirFunc 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 NewSyscallError 

func NewSyscallError(syscall string, err error) error

NewSyscallError returns, as an error, a new SyscallError with the given system call name and error details. As a convenience, if err is nil, NewSyscallError returns nil.

func ReadDirMap 

func ReadDirMap[T any](fs *UnixFS, path string, fn func(DirEntry) (T, error)) ([]T, error)

ReadDirMap . TODO: document

func WalkDir 

func WalkDir(fs Filesystem, root string, fn WalkDirFunc) error

WalkDir walks the file tree rooted at root, calling fn for each file or directory in the tree, including root.

All errors that arise visiting files and directories are filtered by fn: see the WalkDirFunc documentation for details.

The files are walked in lexical order, which makes the output deterministic but requires WalkDir to read an entire directory into memory before proceeding to walk that directory.

WalkDir does not follow symbolic links found in directories, but if root itself is a symbolic link, its target will be walked.

Types

type CountedReader 

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

CountedReader is a reader that counts the amount of data read from the underlying reader.

func NewCountedReader 

func NewCountedReader(r io.Reader) *CountedReader

NewCountedReader returns a new countedReader that counts the amount of bytes read from the underlying reader.

func (*CountedReader) BytesRead 

func (r *CountedReader) BytesRead() int64

BytesRead returns the amount of bytes that have been read from the underlying reader.

func (*CountedReader) Error 

func (r *CountedReader) Error() error

Error returns the error from the reader if any. If the error is an EOF, nil will be returned.

func (*CountedReader) Read 

func (r *CountedReader) Read(p []byte) (int, error)

Read reads bytes from the underlying reader while tracking the total amount of bytes read.

type CountedWriter 

type CountedWriter struct {
	File
	// contains filtered or unexported fields
}

CountedWriter is a writer that counts the amount of data written to the underlying writer.

func NewCountedWriter 

func NewCountedWriter(f File) *CountedWriter

NewCountedWriter returns a new countedWriter that counts the amount of bytes written to the underlying writer.

func (*CountedWriter) BytesWritten 

func (w *CountedWriter) BytesWritten() int64

BytesWritten returns the amount of bytes that have been written to the underlying writer.

func (*CountedWriter) Error 

func (w *CountedWriter) Error() error

Error returns the error from the writer if any. If the error is an EOF, nil will be returned.

func (*CountedWriter) ReadFrom 

func (w *CountedWriter) ReadFrom(r io.Reader) (n int64, err error)

func (*CountedWriter) Write 

func (w *CountedWriter) Write(p []byte) (int, error)

Write writes bytes to the underlying writer while tracking the total amount of bytes written.

type DirEntry 

type DirEntry = iofs.DirEntry

DirEntry is an entry read from a directory.

type File 

type File interface {
	// Name returns the base name of the file.
	Name() string

	// Stat returns the FileInfo structure describing the file.
	// If there is an error, it will be of type *PathError.
	Stat() (FileInfo, error)

	// ReadDir reads the contents of the directory associated with the file f
	// and returns a slice of DirEntry values in directory order.
	// Subsequent calls on the same file will yield later DirEntry records in the directory.
	//
	// If n > 0, ReadDir returns at most n DirEntry records.
	// In this case, if ReadDir returns an empty slice, it will return an error explaining why.
	// At the end of a directory, the error is io.EOF.
	//
	// If n <= 0, ReadDir returns all the DirEntry records remaining in the directory.
	// When it succeeds, it returns a nil error (not io.EOF).
	ReadDir(n int) ([]DirEntry, error)

	// Readdirnames reads the contents of the directory associated with file
	// and returns a slice of up to n names of files in the directory,
	// in directory order. Subsequent calls on the same file will yield
	// further names.
	//
	// If n > 0, Readdirnames returns at most n names. In this case, if
	// Readdirnames returns an empty slice, it will return a non-nil error
	// explaining why. At the end of a directory, the error is io.EOF.
	//
	// If n <= 0, Readdirnames returns all the names from the directory in
	// a single slice. In this case, if Readdirnames succeeds (reads all
	// the way to the end of the directory), it returns the slice and a
	// nil error. If it encounters an error before the end of the
	// directory, Readdirnames returns the names read until that point and
	// a non-nil error.
	Readdirnames(n int) (names []string, err error)

	// Fd returns the integer Unix file descriptor referencing the open file.
	// If f is closed, the file descriptor becomes invalid.
	// If f is garbage collected, a finalizer may close the file descriptor,
	// making it invalid; see runtime.SetFinalizer for more information on when
	// a finalizer might be run. On Unix systems this will cause the SetDeadline
	// methods to stop working.
	// Because file descriptors can be reused, the returned file descriptor may
	// only be closed through the Close method of f, or by its finalizer during
	// garbage collection. Otherwise, during garbage collection the finalizer
	// may close an unrelated file descriptor with the same (reused) number.
	//
	// As an alternative, see the f.SyscallConn method.
	Fd() uintptr

	// Truncate changes the size of the file.
	// It does not change the I/O offset.
	// If there is an error, it will be of type *PathError.
	Truncate(size int64) error

	io.Closer

	io.Reader
	io.ReaderAt
	io.ReaderFrom

	io.Writer
	io.WriterAt

	io.Seeker
}

File describes readable and/or writable file from a Filesystem.

type FileInfo 

type FileInfo = iofs.FileInfo

FileInfo describes a file and is returned by Stat and Lstat.

type FileMode 

type FileMode = iofs.FileMode

FileMode represents a file's mode and permission bits. The bits have the same definition on all systems, so that information about files can be moved from one system to another portably. Not all bits apply to all systems. The only required bit is ModeDir for directories.

type Filesystem 

type Filesystem interface {
	// Chmod changes the mode of the named file to mode.
	//
	// If the file is a symbolic link, it changes the mode of the link's target.
	// If there is an error, it will be of type *PathError.
	//
	// A different subset of the mode bits are used, depending on the
	// operating system.
	//
	// On Unix, the mode's permission bits, ModeSetuid, ModeSetgid, and
	// ModeSticky are used.
	//
	// On Windows, only the 0200 bit (owner writable) of mode is used; it
	// controls whether the file's read-only attribute is set or cleared.
	// The other bits are currently unused. For compatibility with Go 1.12
	// and earlier, use a non-zero mode. Use mode 0400 for a read-only
	// file and 0600 for a readable+writable file.
	//
	// On Plan 9, the mode's permission bits, ModeAppend, ModeExclusive,
	// and ModeTemporary are used.
	Chmod(name string, mode FileMode) error

	// Chown changes the numeric uid and gid of the named file.
	//
	// If the file is a symbolic link, it changes the uid and gid of the link's target.
	// A uid or gid of -1 means to not change that value.
	// If there is an error, it will be of type *PathError.
	//
	// On Windows or Plan 9, Chown always returns the syscall.EWINDOWS or
	// EPLAN9 error, wrapped in *PathError.
	Chown(name string, uid, gid int) error

	// Lchown changes the numeric uid and gid of the named file.
	//
	// If the file is a symbolic link, it changes the uid and gid of the link itself.
	// If there is an error, it will be of type *PathError.
	//
	// On Windows, it always returns the syscall.EWINDOWS error, wrapped
	// in *PathError.
	Lchown(name string, uid, gid int) error

	// Chtimes changes the access and modification times of the named
	// file, similar to the Unix utime() or utimes() functions.
	//
	// The underlying filesystem may truncate or round the values to a
	// less precise time unit.
	//
	// If there is an error, it will be of type *PathError.
	Chtimes(name string, atime, mtime time.Time) error

	// Create creates or truncates the named file. If the file already exists,
	// it is truncated.
	//
	// If the file does not exist, it is created with mode 0666
	// (before umask). If successful, methods on the returned File can
	// be used for I/O; the associated file descriptor has mode O_RDWR.
	// If there is an error, it will be of type *PathError.
	Create(name string) (File, error)

	// Mkdir creates a new directory with the specified name and permission
	// bits (before umask).
	//
	// If there is an error, it will be of type *PathError.
	Mkdir(name 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 (before umask) are used for all
	// directories that MkdirAll creates.
	// If path is already a directory, MkdirAll does nothing
	// and returns nil.
	MkdirAll(path string, perm FileMode) error

	// Open opens the named file for reading.
	//
	// If successful, methods on the returned file can be used for reading; the
	// associated file descriptor has mode O_RDONLY.
	//
	// If there is an error, it will be of type *PathError.
	Open(name string) (File, error)

	// OpenFile is the generalized open call; most users will use Open
	// or Create instead. It opens the named file with specified flag
	// (O_RDONLY etc.).
	//
	// If the file does not exist, and the O_CREATE flag
	// is passed, it is created with mode perm (before umask). If successful,
	// methods on the returned File can be used for I/O.
	//
	// If there is an error, it will be of type *PathError.
	OpenFile(name string, flag int, perm FileMode) (File, error)

	// ReadDir reads the named directory,
	//
	// returning all its directory entries sorted by filename.
	// If an error occurs reading the directory, ReadDir returns the entries it
	// was able to read before the error, along with the error.
	ReadDir(name string) ([]DirEntry, error)

	// Remove removes the named file or (empty) directory.
	//
	// If there is an error, it will be of type *PathError.
	Remove(name string) error

	// RemoveAll removes path and any children it contains.
	//
	// It removes everything it can but returns the first error
	// it encounters. If the path does not exist, RemoveAll
	// returns nil (no error).
	//
	// If there is an error, it will be of type *PathError.
	RemoveAll(path string) error

	// Rename renames (moves) oldpath to newpath.
	//
	// If newpath already exists and is not a directory, Rename replaces it.
	// OS-specific restrictions may apply when oldpath and newpath are in different directories.
	// Even within the same directory, on non-Unix platforms Rename is not an atomic operation.
	//
	// If there is an error, it will be of type *LinkError.
	Rename(oldname, newname string) error

	// Stat returns a FileInfo describing the named file.
	//
	// If there is an error, it will be of type *PathError.
	Stat(name string) (FileInfo, error)

	// Lstat returns a FileInfo describing the named file.
	//
	// If the file is a symbolic link, the returned FileInfo
	// describes the symbolic link. Lstat makes no attempt to follow the link.
	//
	// If there is an error, it will be of type *PathError.
	Lstat(name string) (FileInfo, error)

	// Symlink creates newname as a symbolic link to oldname.
	//
	// On Windows, a symlink to a non-existent oldname creates a file symlink;
	// if oldname is later created as a directory the symlink will not work.
	//
	// If there is an error, it will be of type *LinkError.
	Symlink(oldname, newname string) error

	// WalkDir walks the file tree rooted at root, calling fn for each file or
	// directory in the tree, including root.
	//
	// All errors that arise visiting files and directories are filtered by fn:
	// see the [WalkDirFunc] documentation for details.
	//
	// The files are walked in lexical order, which makes the output deterministic
	// but requires WalkDir to read an entire directory into memory before proceeding
	// to walk that directory.
	//
	// WalkDir does not follow symbolic links found in directories,
	// but if root itself is a symbolic link, its target will be walked.
	WalkDir(root string, fn WalkDirFunc) error
}

Filesystem represents a filesystem capable of performing I/O operations.

type LinkError 

type LinkError = os.LinkError

LinkError records an error during a link or symlink or rename system call and the paths that caused it.

type PathError 

type PathError = iofs.PathError

PathError records an error and the operation and file path that caused it.

type Quota 

type Quota struct {
	// fs is the underlying filesystem that runs the actual I/O operations.
	*UnixFS
	// contains filtered or unexported fields
}

Quota . TODO: document

func NewQuota 

func NewQuota(fs *UnixFS, limit int64) *Quota

NewQuota . TODO: document

func (*Quota) Add 

func (fs *Quota) Add(i int64) int64

Add adds `i` to the tracked usage total.

func (*Quota) CanFit 

func (fs *Quota) CanFit(size int64) bool

CanFit checks if the given size can fit in the filesystem without exceeding the limit of the filesystem.

func (*Quota) Close 

func (fs *Quota) Close() (err error)

Close closes the filesystem.

func (*Quota) Limit 

func (fs *Quota) Limit() int64

Limit returns the limit of the filesystem.

func (*Quota) Remove 

func (fs *Quota) Remove(name string) error

func (*Quota) RemoveAll 

func (fs *Quota) RemoveAll(name string) error

RemoveAll removes path and any children it contains.

It removes everything it can but returns the first error it encounters. If the path does not exist, RemoveAll returns nil (no error).

If there is an error, it will be of type *PathError.

func (*Quota) SetLimit 

func (fs *Quota) SetLimit(newLimit int64) int64

SetLimit returns the limit of the filesystem.

func (*Quota) SetUsage 

func (fs *Quota) SetUsage(newUsage int64) int64

SetUsage updates the total usage of the filesystem.

func (*Quota) Usage 

func (fs *Quota) Usage() int64

Usage returns the current usage of the filesystem.

type SyscallError 

type SyscallError = os.SyscallError

SyscallError records an error from a specific system call.

type UnixFS 

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

UnixFS is a filesystem that uses the unix package to make io calls.

This is used for proper sand-boxing and full control over the exact syscalls being performed.

func NewUnixFS 

func NewUnixFS(basePath string, useOpenat2 bool) (*UnixFS, error)

NewUnixFS creates a new sandboxed unix filesystem. BasePath is used as the sandbox path, operations on BasePath itself are not allowed, but any operations on its descendants are. Symlinks pointing outside BasePath are checked and prevented from enabling an escape in a non-raceable manor.

func (*UnixFS) BasePath 

func (fs *UnixFS) BasePath() string

BasePath returns the base path of the UnixFS sandbox, file operations pointing outside this path are prohibited and will be blocked by all operations implemented by UnixFS.

func (*UnixFS) Chmod 

func (fs *UnixFS) Chmod(name string, mode FileMode) error

Chmod changes the mode of the named file to mode.

If the file is a symbolic link, it changes the mode of the link's target. If there is an error, it will be of type *PathError.

A different subset of the mode bits are used, depending on the operating system.

On Unix, the mode's permission bits, ModeSetuid, ModeSetgid, and ModeSticky are used.

On Windows, only the 0200 bit (owner writable) of mode is used; it controls whether the file's read-only attribute is set or cleared. The other bits are currently unused. For compatibility with Go 1.12 and earlier, use a non-zero mode. Use mode 0400 for a read-only file and 0600 for a readable+writable file.

On Plan 9, the mode's permission bits, ModeAppend, ModeExclusive, and ModeTemporary are used.

func (*UnixFS) Chown 

func (fs *UnixFS) Chown(name string, uid, gid int) error

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

If the file is a symbolic link, it changes the uid and gid of the link's target. A uid or gid of -1 means to not change that value. If there is an error, it will be of type *PathError.

On Windows or Plan 9, Chown always returns the syscall.EWINDOWS or EPLAN9 error, wrapped in *PathError.

func (*UnixFS) Chownat 

func (fs *UnixFS) Chownat(dirfd int, name string, uid, gid int) error

Chownat is like Chown but allows passing an existing directory file descriptor rather than needing to resolve one.

func (*UnixFS) Chtimes 

func (fs *UnixFS) Chtimes(name string, atime, mtime time.Time) error

Chtimes changes the access and modification times of the named file, similar to the Unix utime() or utimes() functions.

The underlying filesystem may truncate or round the values to a less precise time unit.

If there is an error, it will be of type *PathError.

func (*UnixFS) Chtimesat 

func (fs *UnixFS) Chtimesat(dirfd int, name string, atime, mtime time.Time) error

Chtimesat is like Chtimes but allows passing an existing directory file descriptor rather than needing to resolve one.

func (*UnixFS) Close 

func (fs *UnixFS) Close() error

Close releases the file descriptor used to sandbox operations within the base path of the filesystem.

func (*UnixFS) Create 

func (fs *UnixFS) Create(name string) (File, error)

Create creates or truncates the named file. If the file already exists, it is truncated.

If the file does not exist, it is created with mode 0666 (before umask). If successful, methods on the returned File can be used for I/O; the associated file descriptor has mode O_RDWR. If there is an error, it will be of type *PathError.

func (*UnixFS) Lchown 

func (fs *UnixFS) Lchown(name string, uid, gid int) error

Lchown changes the numeric uid and gid of the named file.

If the file is a symbolic link, it changes the uid and gid of the link itself. If there is an error, it will be of type *PathError.

On Windows, it always returns the syscall.EWINDOWS error, wrapped in *PathError.

func (*UnixFS) Lchownat 

func (fs *UnixFS) Lchownat(dirfd int, name string, uid, gid int) error

Lchownat is like Lchown but allows passing an existing directory file descriptor rather than needing to resolve one.

func (*UnixFS) Lstat 

func (fs *UnixFS) Lstat(name string) (FileInfo, error)

Lstat returns a FileInfo describing the named file.

If the file is a symbolic link, the returned FileInfo describes the symbolic link. Lstat makes no attempt to follow the link.

If there is an error, it will be of type *PathError.

func (*UnixFS) Lstatat 

func (fs *UnixFS) Lstatat(dirfd int, name string) (FileInfo, error)

Lstatat is like Lstat but allows passing an existing directory file descriptor rather than needing to resolve one.

func (*UnixFS) Mkdir 

func (fs *UnixFS) Mkdir(name string, mode FileMode) error

Mkdir creates a new directory with the specified name and permission bits (before umask).

If there is an error, it will be of type *PathError.

func (*UnixFS) MkdirAll 

func (fs *UnixFS) MkdirAll(name string, mode 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 (before umask) are used for all directories that MkdirAll creates. If path is already a directory, MkdirAll does nothing and returns nil.

func (*UnixFS) Mkdirat 

func (fs *UnixFS) Mkdirat(dirfd int, name string, mode FileMode) error

func (*UnixFS) Open 

func (fs *UnixFS) Open(name string) (File, error)

Open opens the named file for reading.

If successful, methods on the returned file can be used for reading; the associated file descriptor has mode O_RDONLY.

If there is an error, it will be of type *PathError.

func (*UnixFS) OpenFile 

func (fs *UnixFS) OpenFile(name string, flag int, mode FileMode) (File, error)

OpenFile is the generalized open call; most users will use Open or Create instead. It opens the named file with specified flag (O_RDONLY etc.).

If the file does not exist, and the O_CREATE flag is passed, it is created with mode perm (before umask). If successful, methods on the returned File can be used for I/O.

If there is an error, it will be of type *PathError.

func (*UnixFS) OpenFileat 

func (fs *UnixFS) OpenFileat(dirfd int, name string, flag int, mode FileMode) (File, error)

func (*UnixFS) ReadDir 

func (fs *UnixFS) ReadDir(path string) ([]DirEntry, error)

ReadDir reads the named directory,

returning all its directory entries sorted by filename. If an error occurs reading the directory, ReadDir returns the entries it was able to read before the error, along with the error.

func (*UnixFS) Remove 

func (fs *UnixFS) Remove(name string) error

Remove removes the named file or (empty) directory.

If there is an error, it will be of type *PathError.

func (*UnixFS) RemoveAll 

func (fs *UnixFS) RemoveAll(name string) error

RemoveAll removes path and any children it contains.

It removes everything it can but returns the first error it encounters. If the path does not exist, RemoveAll returns nil (no error).

If there is an error, it will be of type *PathError.

func (*UnixFS) RemoveStat 

func (fs *UnixFS) RemoveStat(name string) (FileInfo, error)

RemoveStat is a combination of Stat and Remove, it is used to more efficiently remove a file when the caller needs to stat it before removing it.

This optimized function exists for our QuotaFS abstraction, which needs to track writes to a filesystem. When removing a file, the QuotaFS needs to know if the entry is a file and if so, how large it is. Because we need to Stat a file in order to get its mode and size, we will already know if the entry needs to be removed by using Unlink or Rmdir. The standard `Remove` method just tries both Unlink and Rmdir (in that order) as it ends up usually being faster and more efficient than calling Stat + the proper operation in the first place.

func (*UnixFS) Rename 

func (fs *UnixFS) Rename(oldpath, newpath string) error

Rename renames (moves) oldpath to newpath.

If newpath already exists and is not a directory, Rename replaces it. OS-specific restrictions may apply when oldpath and newpath are in different directories. Even within the same directory, on non-Unix platforms Rename is not an atomic operation.

If there is an error, it will be of type *LinkError.

func (*UnixFS) SafePath 

func (fs *UnixFS) SafePath(path string) (int, string, func(), error)

func (*UnixFS) Stat 

func (fs *UnixFS) Stat(name string) (FileInfo, error)

Stat returns a FileInfo describing the named file.

If there is an error, it will be of type *PathError.

func (*UnixFS) Statat 

func (fs *UnixFS) Statat(dirfd int, name string) (FileInfo, error)

Statat is like Stat but allows passing an existing directory file descriptor rather than needing to resolve one. 

func (fs *UnixFS) Symlink(oldpath, newpath string) error

Symlink creates newname as a symbolic link to oldname.

On Windows, a symlink to a non-existent oldname creates a file symlink; if oldname is later created as a directory the symlink will not work.

If there is an error, it will be of type *LinkError.

func (*UnixFS) Touch 

func (fs *UnixFS) Touch(path string, flag int, mode FileMode) (File, error)

Touch will attempt to open a file for reading and/or writing. If the file does not exist it will be created, and any missing parent directories will also be created. The opened file may be truncated, only if `flag` has O_TRUNC set.

func (*UnixFS) WalkDir 

func (fs *UnixFS) WalkDir(root string, fn WalkDirFunc) error

WalkDir walks the file tree rooted at root, calling fn for each file or directory in the tree, including root.

All errors that arise visiting files and directories are filtered by fn: see the WalkDirFunc documentation for details.

The files are walked in lexical order, which makes the output deterministic but requires WalkDir to read an entire directory into memory before proceeding to walk that directory.

WalkDir does not follow symbolic links found in directories, but if root itself is a symbolic link, its target will be walked.

func (*UnixFS) WalkDirat 

func (fs *UnixFS) WalkDirat(dirfd int, name string, fn WalkDiratFunc) error

type WalkDirFunc 

type WalkDirFunc func(path string, d DirEntry, err error) error

WalkDirFunc is the type of the function called by WalkDir to visit each file or directory.

The path argument contains the argument to WalkDir as a prefix. That is, if WalkDir is called with root argument "dir" and finds a file named "a" in that directory, the walk function will be called with argument "dir/a".

The d argument is the DirEntry for the named path.

The error result returned by the function controls how WalkDir continues. If the function returns the special value SkipDir, WalkDir skips the current directory (path if d.IsDir() is true, otherwise path's parent directory). If the function returns the special value SkipAll, WalkDir skips all remaining files and directories. Otherwise, if the function returns a non-nil error, WalkDir stops entirely and returns that error.

The err argument reports an error related to path, signaling that WalkDir will not walk into that directory. The function can decide how to handle that error; as described earlier, returning the error will cause WalkDir to stop walking the entire tree.

WalkDir calls the function with a non-nil err argument in two cases.

First, if the initial [Stat] on the root directory fails, WalkDir calls the function with path set to root, d set to nil, and err set to the error from [fs.Stat].

Second, if a directory's ReadDir method (see [ReadDirFile]) fails, WalkDir calls the function with path set to the directory's path, d set to an DirEntry describing the directory, and err set to the error from ReadDir. In this second case, the function is called twice with the path of the directory: the first call is before the directory read is attempted and has err set to nil, giving the function a chance to return SkipDir or SkipAll and avoid the ReadDir entirely. The second call is after a failed ReadDir and reports the error from ReadDir. (If ReadDir succeeds, there is no second call.)

type WalkDiratFunc 

type WalkDiratFunc func(dirfd int, name, relative string, d DirEntry, err error) error

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.