io/fs
import "io/fs"
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. # Path Names The interfaces in this package all operate on the same path name syntax, regardless of the host operating system. Path names 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...
Go 1.26.1
Variables
var ( ErrInvalid = errInvalid() // "invalid argument" ErrPermission = errPermission() // "permission denied" ErrExist = errExist() // "file already exists" ErrNotExist = errNo...
Generic file system errors. Errors returned by file systems can be tested against these errors using [errors.Is].
io/fs/fs.go:158
var ( ErrInvalid = errInvalid() // "invalid argument" ErrPermission = errPermission() // "permission denied" ErrExist = errExist() // "file already exists" ErrNotExist = errNo...
Generic file system errors. Errors returned by file systems can be tested against these errors using [errors.Is].
io/fs/fs.go:156
var ( ErrInvalid = errInvalid() // "invalid argument" ErrPermission = errPermission() // "permission denied" ErrExist = errExist() // "file already exists" ErrNotExist = errNo...
Generic file system errors. Errors returned by file systems can be tested against these errors using [errors.Is].
io/fs/fs.go:154
var ( ErrInvalid = errInvalid() // "invalid argument" ErrPermission = errPermission() // "permission denied" ErrExist = errExist() // "file already exists" ErrNotExist = errNo...
Generic file system errors. Errors returned by file systems can be tested against these errors using [errors.Is].
io/fs/fs.go:157
var ( ErrInvalid = errInvalid() // "invalid argument" ErrPermission = errPermission() // "permission denied" ErrExist = errExist() // "file already exists" ErrNotExist = errNo...
Generic file system errors. Errors returned by file systems can be tested against these errors using [errors.Is].
io/fs/fs.go:155
var SkipAll = errors.New("skip everything and stop the walk")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.
io/fs/walk.go:20
var SkipDir = errors.New("skip this directory")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.
io/fs/walk.go:15
Functions
func FileInfoToDirEntry(info FileInfo) DirEntry
FileInfoToDirEntry returns a [DirEntry] that returns information from info. If info is nil, FileInfoToDirEntry returns nil.
io/fs/readdir.go:79
func FormatDirEntry(dir DirEntry) string
FormatDirEntry returns a formatted version of dir for human readability. Implementations of [DirEntry] can call this from a String method. The outputs for a directory named subdir and a file named hello.go are: d subdir/ - hello.go
io/fs/format.go:60
func FormatFileInfo(info FileInfo) string
FormatFileInfo returns a formatted version of info for human readability. Implementations of [FileInfo] can call this from a String method. The output for a file named "hello.go", 100 bytes, mode 0o644, created January 1, 1970 at noon is -rw-r--r-- 100 1970-01-01 12:00:00 hello.go
io/fs/format.go:17
func Glob(fsys FS, pattern string) ([]string, 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. 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 ...
io/fs/glob.go:33
func Lstat(fsys FS, 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 fsys does not implement [ReadLinkFS], then Lstat is identical to [Stat].
io/fs/readlink.go:39
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.
io/fs/readdir.go:29
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].
io/fs/readfile.go:32
func ReadLink(fsys FS, name string) (string, error)
ReadLink returns the destination of the named symbolic link. If fsys does not implement [ReadLinkFS], then ReadLink returns an error.
io/fs/readlink.go:26
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.
io/fs/stat.go:20
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, ReadLink, Lstat, and Glob appropriately. Note that Sub(os.DirFS("/"), "prefix") is equivalent to os.DirFS("/prefix") and t...
io/fs/sub.go:35
func ValidPath(name string) bool
ValidPath reports whether the given path name is valid for use in a call to Open. 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. See the [Path Names] section for more details. [Path Names]: https://pkg.go.dev/io/fs#hdr-Path_Names
io/fs/fs.go:64
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...
io/fs/walk.go:117
Types
type DirEntry interface {
// Name returns the name of the file (or subdirectory) described by the entry.
// This name is only the final element of the path (the base name), not the entire path.
...A DirEntry is an entry read from a directory (using the [ReadDir] function or a [ReadDirFile]'s ReadDir method).
io/fs/fs.go:103
type File interface {
Stat() (FileInfo, error)
Read([]byte) (int, error)
Close() error
}A File provides access to a single file. The File interface is the minimum implementation required of the file. Directory files should also implement [ReadDirFile]. A file may implement [io.ReaderAt] or [io.Seeker] as optimizations.
io/fs/fs.go:95
type FileInfo interface {
Name() string // base name of the file
Size() int64 // length in bytes for regular files; system-dependent for others
Mode() FileMode // file mode bits...A FileInfo describes a file and is returned by [Stat].
io/fs/fs.go:168
type FileMode uint32
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.
io/fs/fs.go:182
func (m FileMode) IsDir() bool
IsDir reports whether m describes a directory. That is, it tests for the [ModeDir] bit being set in m.
io/fs/fs.go:240
func (m FileMode) IsRegular() bool
IsRegular reports whether m describes a regular file. That is, it tests that no mode type bits are set.
io/fs/fs.go:246
func (m FileMode) Perm() FileMode
Perm returns the Unix permission bits in m (m & [ModePerm]).
io/fs/fs.go:251
func (m FileMode) String() string
io/fs/fs.go:212
func (m FileMode) Type() FileMode
Type returns type bits in m (m & [ModeType]).
io/fs/fs.go:256
type FS interface {
// Open opens the named file.
// [File.Close] must be called to release any associated resources.
//
// When Open returns an error, it should be of type *PathError
// with ...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. [testing/fstest.TestFS] may be used to test implementations of an FS for correctness.
io/fs/fs.go:40
type GlobFS interface {
FS
// Glob returns the names of all files matching pattern,
// providing an implementation of the top-level
// Glob function.
Glob(pattern string) ([]string, error)
}A GlobFS is a file system with a Glob method.
io/fs/glob.go:12
type PathError struct {
Op string
Path string
Err error
}PathError records an error and the operation and file path that caused it.
io/fs/fs.go:261
func (e *PathError) Error() string
io/fs/fs.go:267
func (e *PathError) Timeout() bool
Timeout reports whether this error represents a timeout.
io/fs/fs.go:272
func (e *PathError) Unwrap() error
io/fs/fs.go:269
type ReadDirFile interface {
File
// ReadDir reads the contents of the directory and returns
// a slice of up to n DirEntry values in directory order.
// Subsequent calls on the same file will...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.)
io/fs/fs.go:129
type ReadDirFS interface {
FS
// ReadDir reads the named directory
// and returns a list of directory entries sorted by filename.
ReadDir(name string) ([]DirEntry, error)
}ReadDirFS is the interface implemented by a file system that provides an optimized implementation of [ReadDir].
io/fs/readdir.go:15
type ReadFileFS interface {
FS
// ReadFile reads the named file and returns its contents.
// A successful call returns a nil error, not io.EOF.
// (Because ReadFile reads the whole file, the e...ReadFileFS is the interface implemented by a file system that provides an optimized implementation of [ReadFile].
io/fs/readfile.go:11
type ReadLinkFS interface {
FS
// ReadLink returns the destination of the named symbolic link.
// If there is an error, it should be of type [*PathError].
ReadLink(name string) (string, error)...ReadLinkFS is the interface implemented by a file system that supports reading symbolic links.
io/fs/readlink.go:9
type StatFS interface {
FS
// Stat returns a FileInfo describing the file.
// If there is an error, it should be of type *PathError.
Stat(name string) (FileInfo, error)
}A StatFS is a file system with a Stat method.
io/fs/stat.go:8
type SubFS interface {
FS
// Sub returns an FS corresponding to the subtree rooted at dir.
Sub(dir string) (FS, error)
}A SubFS is a file system with a Sub method.
io/fs/sub.go:13
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 [SkipDi...
io/fs/walk.go:69