8.14 io/fs — Specification¶

A compact reference of every interface, function, type, and constant that the package exports, along with the contract each one obeys.

1. Core interfaces¶

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

type File interface {
    Stat() (FileInfo, error)
    Read([]byte) (int, error)
    Close() error
}

type FileInfo interface {
    Name() string
    Size() int64
    Mode() FileMode
    ModTime() time.Time
    IsDir() bool
    Sys() any
}

type DirEntry interface {
    Name() string
    IsDir() bool
    Type() FileMode
    Info() (FileInfo, error)
}

type ReadDirFile interface {
    File
    ReadDir(n int) ([]DirEntry, error)
}

2. Optional capability interfaces¶

Each one embeds FS. An implementation that satisfies the optional interface speeds up the corresponding helper; otherwise the helper falls back to a default built on Open.

3. Helper functions¶

4. WalkDirFunc¶

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

Sentinel returns:

5. Error sentinels¶

var (
    ErrInvalid    = errors.New("invalid argument")
    ErrPermission = errors.New("permission denied")
    ErrExist      = errors.New("file already exists")
    ErrNotExist   = errors.New("file does not exist")
    ErrClosed     = errors.New("file already closed")
)

These are aliased to os.ErrInvalid, os.ErrPermission, os.ErrExist, os.ErrNotExist, os.ErrClosed respectively. Use errors.Is(err, fs.ErrXxx) for matching.

6. The PathError type¶

type PathError struct {
    Op   string
    Path string
    Err  error
}

func (e *PathError) Error() string
func (e *PathError) Unwrap() error
func (e *PathError) Timeout() bool

Aliased to *os.PathError. Returned by every method that takes a name when an error occurs.

7. The FileMode type¶

type FileMode uint32

Bitfield. The kind bits:

Methods on FileMode:

8. ValidPath rules¶

A name n satisfies ValidPath(n) == true if:

1. n is non-empty.
2. n == "." (allowed) or every segment of n (after splitting on "/") is non-empty, not ".", and not "..".
3. n does not start or end with "/".
4. n does not contain consecutive "/" characters.

Any other name fails. Implementations should reject failing names with *PathError{Op, Path: n, Err: ErrInvalid}.

9. Open contract¶

Reject invalid names with *PathError{Op: "open", Path: name, Err: ErrInvalid}. Return ErrNotExist for missing files, ErrPermission for access denied. Otherwise return a File whose first Read produces the first byte and whose Stat reports metadata. Open(".") must return a directory file (implementing ReadDirFile).

10. File method contract¶

Stat() returns metadata. May be called any number of times.

Read(p []byte) follows the io.Reader contract. In particular:

• Short reads are legal.
• May return (n > 0, io.EOF) or (n > 0, nil) followed by (0, io.EOF).
• After Close, returns an error wrapping ErrClosed.

Close() releases resources. After the first call:

• Subsequent operations should return errors wrapping ErrClosed.
• Behavior of a second Close is implementation-defined; convention is to return an error wrapping ErrClosed.

11. ReadDirFile.ReadDir(n int)¶

Order is implementation-defined; the package-level fs.ReadDir sorts the result.

12. WalkDir algorithm¶

Walks fsys from root depth-first in lexical order. The callback fn is called once per visited entry; if ReadDir fails for a directory, fn is called a second time with the non-nil error. Sentinel returns: SkipDir, SkipAll, or any other error. Symlinks are not followed.

13. Glob pattern grammar (path.Match)¶

Not supported: **, {a,b}, negation by !.

Pattern errors return path.ErrBadPattern.

14. Sub semantics¶

fs.Sub(fsys, dir) returns an FS rooted at dir. Names are joined with dir and passed to fsys.Open. If fsys implements SubFS, its Sub(dir) is called instead. fs.Sub(fsys, ".") returns fsys unchanged. dir is validated with ValidPath.

15. Concrete implementations¶

os.DirFS does not prevent symlink escape; for confined access use os.OpenRoot(root).FS() (Go 1.24+).

16. fstest.TestFS¶

func TestFS(fsys fs.FS, expected ...string) error

Walks the FS, calls every method on every name, checks invariants, and confirms each expected path is present. Returns nil on success.

17. Concurrency¶

The package makes no claims. Concrete implementations: os.DirFS, embed.FS, fstest.MapFS are all safe for concurrent Open; returned files are single-goroutine. Custom implementations should at minimum permit concurrent Open.

18. Cross-references¶

• junior.md — friendly walkthrough.
• middle.md — building your own FS.
• senior.md — exact contract and edge cases.
• The official package docs: io/fs.