fs

Documentation

Overview

Package fs defines basic interfaces to a file system. A file system can be provided by the host operating system but also by other packages.

Index

• Constants
• Variables
• func Glob(fsys FS, pattern string) (matches []string, err error)
• func ReadFile(fsys FS, name string) ([]byte, error)
• func ValidPath(name string) bool
• func WalkDir(fsys FS, root string, fn WalkDirFunc) error
• type DirEntry
  • func ReadDir(fsys FS, name string) ([]DirEntry, error)
• type FS
  • func DirFS(dir string) FS
  • func Sub(fsys FS, dir string) (FS, error)
• type File
• type FileInfo
  • func Stat(fsys FS, name string) (FileInfo, error)
• type FileMode
• type GlobFS
• type PathError
• type ReadDirFS
• type ReadDirFile
• type ReadFileFS
• type StatFS
• type SubFS
• type WalkDirFunc

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

	ModeType = fs.ModeType // Mask for the type bits. For regular files, none will be set.

	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 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 Glob

func Glob(fsys FS, pattern string) (matches []string, err error)

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 (assuming the Separator is '/').

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 ReadFile

func ReadFile(fsys FS, name string) ([]byte, error)

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 ValidPath

func ValidPath(name string) bool

ValidPath reports whether the given path name is valid for use in a call to Open. Path names passed to open are unrooted, slash-separated sequences of path elements, like “x/y/z”. Path names must not contain a “.” or “..” or empty element, except for the special case that the root directory is named “.”.

Paths are slash-separated on all systems, even Windows. Backslashes must not appear in path names.

func WalkDir

func WalkDir(fsys FS, 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 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 DirEntry

type DirEntry = fs.DirEntry

A DirEntry is an entry read from a directory (using the ReadDir function or a ReadDirFile's ReadDir method).

func ReadDir

func ReadDir(fsys FS, name string) ([]DirEntry, error)

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.

type FS

type FS = fs.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

func DirFS(dir string) FS

DirFS returns a file system 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

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

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

type File = fs.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 FileInfo

type FileInfo = fs.FileInfo

A FileInfo describes a file and is returned by Stat.

func Stat

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

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.

type FileMode

type FileMode = fs.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 GlobFS

type GlobFS = fs.GlobFS

A GlobFS is a file system with a Glob method.

type PathError

type PathError = fs.PathError

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

type ReadDirFS

type ReadDirFS = fs.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 StatFS

type StatFS = fs.StatFS

A StatFS is a file system with a Stat method.

type SubFS

type SubFS = fs.SubFS

A SubFS is a file system with a Sub method.

type WalkDirFunc

type WalkDirFunc = fs.WalkDirFunc

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

The path argument contains the argument to Walk as a prefix. That is, if Walk 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 directory and file are joined with Join, which may clean the directory name: if Walk is called with the root argument "x/../dir" and finds a file named "a" in that directory, the walk function will be called with argument "dir/a", not "x/../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 os.Lstat 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 os.Lstat.

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.