Go Reference ยท Errors, I/O and Files
Go io/fs package
Reference for Go io/fs: the fs.FS interface, ReadFile, ReadDir, Stat, Glob, Sub, WalkDir, os.DirFS, fstest.MapFS, fs.ErrNotExist and file modes.
The io/fs package (Go 1.16) defines a read-only view of a file system as a tiny interface: fs.FS has one method, Open(name string) (fs.File, error). Anything that can open named files can implement it: the real disk (os.DirFS), files embedded in the binary (embed.FS), a zip archive (zip.Reader), a test fixture (fstest.MapFS) or your own remote storage.
Code written against fs.FS is easy to test and works with any of them. Helper functions such as fs.ReadFile, fs.ReadDir, fs.Stat, fs.Glob, fs.Sub and fs.WalkDir give you convenient operations on top of the minimal interface, and use faster optional methods when the file system provides them.
var fsys fs.FS = os.DirFS("/srv/site") page, err := fs.ReadFile(fsys, "index.html")
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
type FS interface { Open(name string) (File, error) } type File interface { Stat() (FileInfo, error) Read([]byte) (int, error) Close() error } func ReadFile(fsys FS, name string) ([]byte, error) func ReadDir(fsys FS, name string) ([]DirEntry, error) func Stat(fsys FS, name string) (FileInfo, error) func Glob(fsys FS, pattern string) ([]string, error) func Sub(fsys FS, dir string) (FS, error) func WalkDir(fsys FS, root string, fn WalkDirFunc) error func ValidPath(name string) bool func FormatFileInfo(info FileInfo) string
| Type or value | Purpose |
|---|---|
fs.DirEntry |
A directory listing entry: Name, IsDir, Type, Info. |
fs.FileInfo |
Name, size, mode, modification time, IsDir, Sys. |
fs.FileMode |
Type and permission bits; ModeDir, ModeSymlink, ModePerm and so on. |
fs.ReadDirFS, ReadFileFS, StatFS, GlobFS, SubFS |
Optional interfaces a file system may implement for speed. |
fs.ErrNotExist, ErrExist, ErrPermission, ErrInvalid, ErrClosed |
Sentinel errors; use errors.Is. |
fs.PathError |
Operation, path and underlying error. |
fs.SkipDir, fs.SkipAll |
Return values for WalkDir callbacks. |
Errors: invalid names make Open return a *fs.PathError wrapping fs.ErrInvalid; missing files wrap fs.ErrNotExist.
Usage notes
- Names are always slash-separated, never start with
/, never contain.or..elements and are never empty. The root of any file system is".". Check withfs.ValidPath. This holds on Windows too. os.DirFS("dir")does not sandbox symlinks: a link inside the directory can still point outside it. Go 1.24'sos.Rootand itsFS()method give real confinement.- Read-only by design. There is no
Writeinfs.FS; for writing, useos(or theos.Rootmethods). - Accept
fs.FSin your functions (parse templates, load config, serve static files) so tests can pass anfstest.MapFSand production can passembed.FSoros.DirFS. fstest.TestFS(fsys, "expected/files")checks that your own implementation obeys the rules.http.FileServerFS,template.ParseFSandzip.Readerall work withfs.FS, which is the payoff of the abstraction.fs.Globusespath.Matchrules:*never crosses/, and there is no**.fs.WalkDirvsfilepath.WalkDir: the former takes a file system and works with slash paths; the latter walks the real disk using OS paths.- Since Go 1.23,
os.CopyFS(dir, fsys)copies anfs.FSto disk.