Documentation ¶
Overview ¶
Package wrfs provides extension interfaces for the io/fs package that enable creating, updating and removing files and directories. wrfs can work as a drop-in replacement for the io/fs package, as it re-exports the types and functions defined by io/fs.
Index ¶
- Constants
- Variables
- func Chmod(fsys FS, name string, mode FileMode) (err error)
- func Chown(fsys FS, name string, uid, gid int) (err error)
- func Chtimes(fsys FS, name string, atime time.Time, mtime time.Time) (err error)
- func Glob(fsys fs.FS, pattern string) (matches []string, err error)
- func Lchown(fsys FS, name string, uid, gid int) (err error)
- func Link(fsys FS, oldname, newname string) error
- func Mkdir(fsys FS, name string, perm FileMode) error
- func MkdirAll(fsys FS, path string, perm FileMode) error
- func ReadDir(fsys fs.FS, name string) ([]fs.DirEntry, error)
- func ReadFile(fsys fs.FS, name string) ([]byte, error)
- func Readlink(fsys FS, name string) (string, error)
- func Remove(fsys FS, name string) error
- func RemoveAll(fsys FS, removePath string) error
- func Rename(fsys FS, oldpath, newpath string) error
- func SameFile(fsys FS, fi1, fi2 FileInfo) bool
- func Seek(file File, offset int64, whence int) (int64, error)
- func Stat(fsys fs.FS, name string) (fs.FileInfo, error)
- func Symlink(fsys FS, oldname, newname string) error
- func Truncate(fsys FS, name string, size int64) (err error)
- func ValidPath(name string) bool
- func WalkDir(fsys fs.FS, root string, fn fs.WalkDirFunc) error
- func Write(file File, p []byte) (n int, err error)
- type ChmodFS
- type ChmodFile
- type ChownFS
- type ChownFile
- type ChtimesFS
- type ChtimesFile
- type DirEntry
- type FS
- type File
- type FileInfo
- type FileMode
- type GlobFS
- type LchownFS
- type LinkFS
- type LstatFS
- type MkdirAllFS
- type MkdirFS
- type OpenFileFS
- type PathError
- type ReadDirFS
- type ReadDirFile
- type ReadFileFS
- type ReadlinkFS
- type RemoveAllFS
- type RemoveFS
- type RenameFS
- type SameFileFS
- type StatFS
- type SubFS
- type SymlinkFS
- type TruncateFS
- type TruncateFile
- type WalkDirFunc
- type WriteFile
Constants ¶
const ( // The single letters are the abbreviations // used by the String method's formatting. ModeDir = fs.ModeDir // d: is a directory ModeAppend = fs.ModeAppend // a: append-only ModeExclusive = fs.ModeExclusive // l: exclusive use ModeTemporary = fs.ModeTemporary // T: temporary file; Plan 9 only ModeSymlink = fs.ModeSymlink // L: symbolic link ModeDevice = fs.ModeDevice // D: device file ModeNamedPipe = fs.ModeNamedPipe // p: named pipe (FIFO) ModeSocket = fs.ModeSocket // S: Unix domain socket ModeSetuid = fs.ModeSetuid // u: setuid ModeSetgid = fs.ModeSetgid // g: setgid ModeCharDevice = fs.ModeCharDevice // c: Unix character device, when ModeDevice is set ModeSticky = fs.ModeSticky // t: sticky ModeIrregular = fs.ModeIrregular // ?: non-regular file; nothing else is known about this file // Mask for the type bits. For regular files, none will be set. ModeType = fs.ModeType ModePerm = fs.ModePerm // Unix permission bits )
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.
Variables ¶
var ( ErrInvalid = fs.ErrInvalid // "invalid argument" ErrPermission = fs.ErrPermission // "permission denied" ErrExist = fs.ErrExist // "file already exists" ErrNotExist = fs.ErrNotExist // "file does not exist" ErrClosed = fs.ErrClosed // "file already closed" )
Generic file system errors. Errors returned by file systems can be tested against these errors using errors.Is.
var ErrUnsupported = errors.New("unsupported operation")
var SkipDir = fs.SkipDir
SkipDir is used as a return value from WalkDirFuncs 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 Chmod ¶
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.
func Chown ¶
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.
func Chtimes ¶
Chtimes changes the access and modification times of the named file, similar to the Unix utime() or utimes() functions.
func Glob ¶
Glob returns the names of all files matching pattern or nil if there is no matching file. The syntax of patterns is the same as in path.Match. The pattern may describe hierarchical names such as usr/*/bin/ed.
Glob ignores file system errors such as I/O errors reading directories. The only possible returned error is path.ErrBadPattern, reporting that the pattern is malformed.
If fs implements GlobFS, Glob calls fs.Glob. Otherwise, Glob uses ReadDir to traverse the directory tree and look for matches for the pattern.
func Lchown ¶
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.
func MkdirAll ¶
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 ReadDir ¶
ReadDir reads the named directory and returns a list of directory entries sorted by filename.
If fs implements ReadDirFS, ReadDir calls fs.ReadDir. Otherwise ReadDir calls fs.Open and uses ReadDir and Close on the returned file.
func ReadFile ¶
ReadFile reads the named file from the file system fs and returns its contents. A successful call returns a nil error, not io.EOF. (Because ReadFile reads the whole file, the expected EOF from the final Read is not treated as an error to be reported.)
If fs implements ReadFileFS, ReadFile calls fs.ReadFile. Otherwise ReadFile calls fs.Open and uses Read and Close on the returned file.
func Rename ¶
Rename renames (moves) oldpath to newpath. If newpath already exists and is not a directory, Rename replaces it.
func SameFile ¶
SameFile reports whether fi1 and fi2 describe the same file. For example, on Unix this means that the device and inode fields of the two underlying structures are identical; on other systems the decision may be based on the path names.
func Seek ¶
Seek sets the offset for the next Read or Write on file to offset, interpreted according to whence: 0 means relative to the origin of the file, 1 means relative to the current offset, and 2 means relative to the end. It returns the new offset and an error, if any.
func Stat ¶
Stat returns a FileInfo describing the named file from the file system.
If fs implements StatFS, Stat calls fs.Stat. Otherwise, Stat opens the file to stat it.
func ValidPath ¶
ValidPath reports whether the given path name is valid for use in a call to Open.
Path names passed to open are UTF-8-encoded, unrooted, slash-separated sequences of path elements, like “x/y/z”. Path names must not contain an element that is “.” or “..” or the empty string, except for the special case that the root directory is named “.”. Paths must not start or end with a slash: “/x” and “x/” are invalid.
Note that paths are slash-separated on all systems, even Windows. Paths containing other characters such as backslash and colon are accepted as valid, but those characters must never be interpreted by an FS implementation as path element separators.
func WalkDir ¶
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 fs.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 ChmodFS ¶
type ChmodFS interface { FS // 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. Chmod(name string, mode FileMode) error }
ChmodFS is a file system with a Chmod method.
type ChmodFile ¶
type ChmodFile interface { File // Chmod changes the mode of the file to mode. Chmod(mode FileMode) error }
Chmod is a file with a Chmod method.
type ChownFS ¶
type ChownFS interface { FS // 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. Chown(name string, uid, gid int) error }
ChownFS is a file system that supports the Chown function.
type ChownFile ¶
type ChownFile interface { File // Chown changes the numeric uid and gid of the file. // A uid or gid of -1 means to not change that value. Chown(uid, gid int) error }
ChownFile is a file with a Chown method.
type ChtimesFS ¶
type ChtimesFS interface { FS // Chtimes changes the access and modification times of the named file, // similar to the Unix utime() or utimes() functions. Chtimes(name string, atime time.Time, mtime time.Time) error }
ChtimesFS is a file system with a Chtimes method.
type ChtimesFile ¶
type ChtimesFile interface { File // Chtimes changes the access and modification times of the file, // similar to the Unix utime() or utimes() functions. Chtimes(atime time.Time, mtime time.Time) error }
ChtimesFile is a file with a Chtimes method.
type DirEntry ¶
A DirEntry is an entry read from a directory (using the ReadDir function or a ReadDirFile's ReadDir method).
type FS ¶
An FS provides access to a hierarchical file system.
The FS interface is the minimum implementation required of the file system. A file system may implement additional interfaces, such as ReadFileFS, to provide additional or optimized functionality.
func DirFS ¶
DirFS returns a file system (an fs.FS) for the tree of files rooted at the directory dir.
Note that DirFS("/prefix") only guarantees that the Open calls it makes to the operating system will begin with "/prefix": DirFS("/prefix").Open("file") is the same as os.Open("/prefix/file"). So if /prefix/file is a symbolic link pointing outside the /prefix tree, then using DirFS does not stop the access any more than using os.Open does. DirFS is therefore not a general substitute for a chroot-style security mechanism when the directory tree contains arbitrary content.
func Sub ¶
Sub returns an FS corresponding to the subtree rooted at fsys's dir.
If fs implements SubFS, Sub calls returns fsys.Sub(dir). Otherwise, if dir is ".", Sub returns fsys unchanged. Otherwise, Sub returns a new FS implementation sub that, in effect, implements sub.Open(dir) 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 ¶
A File provides access to a single file. The File interface is the minimum implementation required of the file. A file may implement additional interfaces, such as ReadDirFile, ReaderAt, or Seeker, to provide additional or optimized functionality.
type FileMode ¶
A 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 LchownFS ¶
type LchownFS interface { // 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. Lchown(name string, uid, gid int) error }
LchownFS is a file system that supports the Lchown function.
type LinkFS ¶
type LinkFS interface { // Link creates newname as a hard link to the oldname file. Link(oldname, newname string) error }
LinkFS is a file system that supports the Link function.
type LstatFS ¶
type LstatFS interface { // 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. Lstat(name string) (FileInfo, error) }
LstatFS is a file system that supports the Lstat operation.
type MkdirAllFS ¶
type MkdirAllFS interface { FS // 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 }
type MkdirFS ¶
type MkdirFS interface { FS // Mkdir creates a new directory with the specified name and permission bits. Mkdir(name string, perm FileMode) error }
MkdirFS is a file system that supports the Mkdir function.
type OpenFileFS ¶
type OpenFileFS interface { FS // OpenFile 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. OpenFile(name string, flag int, perm FileMode) (File, error) }
OpenFileFS is a file system that supports the OpenFile function.
type ReadDirFS ¶
ReadDirFS is the interface implemented by a file system that provides an optimized implementation of ReadDir.
type ReadDirFile ¶
type ReadDirFile = fs.ReadDirFile
A ReadDirFile is a directory file whose entries can be read with the ReadDir method. Every directory file should implement this interface. (It is permissible for any file to implement this interface, but if so ReadDir should return an error for non-directories.)
type ReadFileFS ¶
type ReadFileFS = fs.ReadFileFS
ReadFileFS is the interface implemented by a file system that provides an optimized implementation of ReadFile.
type ReadlinkFS ¶
type ReadlinkFS interface { // Readlink returns the destination of the named symbolic link. Readlink(name string) (string, error) }
ReadlinkFS is a file system that supports the Readlink function.
type RemoveAllFS ¶
type RemoveAllFS interface { FS // RemoveAll removes path and any children it contains. RemoveAll(path string) error }
RemoveAllFS is a file system that supports the RemoveAll function.
type RemoveFS ¶
type RemoveFS interface { FS // Remove removes the named file or (empty) directory. Remove(name string) error }
RemoveFS is a file system that supports the Remove function.
type SameFileFS ¶
type SameFileFS interface { // SameFile reports whether fi1 and fi2 describe the same file. // For example, on Unix this means that the device and inode fields of the two underlying structures are identical; // on other systems the decision may be based on the path names. SameFile(fi1, fi2 FileInfo) bool }
SameFileFS is a file system that supports the SameFile function.
type SymlinkFS ¶
type SymlinkFS interface { FS // Symlink creates newname as a symbolic link to oldname. Symlink(oldname, newname string) error }
SymlinkFS is a file system with a Symlink method.
type TruncateFS ¶
type TruncateFS interface { FS // Truncate changes the size of the named file. Truncate(name string, size int64) error }
TruncateFS is a file system with a Truncate method.
type TruncateFile ¶
type TruncateFile interface { File // Truncate changes the size of the file. Truncate(size int64) error }
TruncateFile is a file that supports the Truncate method.
type WalkDirFunc ¶
type WalkDirFunc = fs.WalkDirFunc
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 fs.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). 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 fs.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 fails, WalkDir calls the function with path set to the directory's path, d set to an fs.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 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.)
The differences between WalkDirFunc compared to filepath.WalkFunc are:
- The second argument has type fs.DirEntry instead of fs.FileInfo.
- The function is called before reading a directory, to allow SkipDir to bypass the directory read entirely.
- If a directory read fails, the function is called a second time for that directory to report the error.
type WriteFile ¶
WriteFile is a file that can be written to.