fs

Imports

Imports # 

"errors"
"path"
"time"
"internal/oserror"
"time"
"unicode/utf8"
"path"
"errors"
"internal/bytealg"
"slices"
"io"
"errors"
"path"

Constants & Variables

ErrClosed var #

Generic file system errors. Errors returned by file systems can be tested against these errors using [errors.Is].

var ErrClosed = *ast.CallExpr

ErrExist var #

Generic file system errors. Errors returned by file systems can be tested against these errors using [errors.Is].

var ErrExist = *ast.CallExpr

ErrInvalid var #

Generic file system errors. Errors returned by file systems can be tested against these errors using [errors.Is].

var ErrInvalid = *ast.CallExpr

ErrNotExist var #

Generic file system errors. Errors returned by file systems can be tested against these errors using [errors.Is].

var ErrNotExist = *ast.CallExpr

ErrPermission var #

Generic file system errors. Errors returned by file systems can be tested against these errors using [errors.Is].

var ErrPermission = *ast.CallExpr

ModeAppend const #

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.

const ModeAppend

ModeCharDevice const #

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.

const ModeCharDevice

ModeDevice const #

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.

const ModeDevice

ModeDir const #

The single letters are the abbreviations used by the String method's formatting.

const ModeDir FileMode = *ast.BinaryExpr

ModeExclusive const #

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.

const ModeExclusive

ModeIrregular const #

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.

const ModeIrregular

ModeNamedPipe const #

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.

const ModeNamedPipe

ModePerm const #

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.

const ModePerm FileMode = 0777

ModeSetgid const #

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.

const ModeSetgid

ModeSetuid const #

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.

const ModeSetuid

ModeSocket const #

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.

const ModeSocket

ModeSticky const #

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.

const ModeSticky

ModeTemporary const #

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.

const ModeTemporary

ModeType const #

Mask for the type bits. For regular files, none will be set.

const ModeType = *ast.BinaryExpr

SkipAll var #

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.

var SkipAll = *ast.CallExpr

SkipDir var #

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.

var SkipDir = *ast.CallExpr

Type Aliases

FileMode type #

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 FileMode uint32

WalkDirFunc type #

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 [SkipDir], WalkDir skips the current directory (path if d.IsDir() is true, otherwise path's parent directory). If the function returns the special value [SkipAll], WalkDir skips all remaining files and directories. 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 [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 (see [ReadDirFile]) fails, WalkDir calls the function with path set to the directory's path, d set to an [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] or [SkipAll] 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 [path/filepath.WalkFunc] are: - The second argument has type [DirEntry] instead of [FileInfo]. - The function is called before reading a directory, to allow [SkipDir] or [SkipAll] to bypass the directory read entirely or skip all remaining files and directories respectively. - If a directory read fails, the function is called a second time for that directory to report the error.

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

Interfaces

DirEntry interface #

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

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

FS interface #

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.

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

File interface #

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.

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

FileInfo interface #

A FileInfo describes a file and is returned by [Stat].

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

GlobFS interface #

A GlobFS is a file system with a Glob method.

type GlobFS interface {
FS
Glob(pattern string) ([]string, error)
}

ReadDirFS interface #

ReadDirFS is the interface implemented by a file system that provides an optimized implementation of [ReadDir].

type ReadDirFS interface {
FS
ReadDir(name string) ([]DirEntry, error)
}

ReadDirFile interface #

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 ReadDirFile interface {
File
ReadDir(n int) ([]DirEntry, error)
}

ReadFileFS interface #

ReadFileFS is the interface implemented by a file system that provides an optimized implementation of [ReadFile].

type ReadFileFS interface {
FS
ReadFile(name string) ([]byte, error)
}

StatFS interface #

A StatFS is a file system with a Stat method.

type StatFS interface {
FS
Stat(name string) (FileInfo, error)
}

SubFS interface #

A SubFS is a file system with a Sub method.

type SubFS interface {
FS
Sub(dir string) (FS, error)
}

Structs

PathError struct #

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

type PathError struct {
Op string
Path string
Err error
}

dirInfo struct #

dirInfo is a DirEntry based on a FileInfo.

type dirInfo struct {
fileInfo FileInfo
}

subFS struct # 

type subFS struct {
fsys FS
dir string
}

Functions

Error method # 

func (e *PathError) Error() string

FileInfoToDirEntry function #

FileInfoToDirEntry returns a [DirEntry] that returns information from info. If info is nil, FileInfoToDirEntry returns nil.

func FileInfoToDirEntry(info FileInfo) DirEntry

FormatDirEntry function #

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

func FormatDirEntry(dir DirEntry) string

FormatFileInfo function #

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

func FormatFileInfo(info FileInfo) string

Glob function #

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 Glob(fsys FS, pattern string) (matches []string, err error)

Glob method # 

func (f *subFS) Glob(pattern string) ([]string, error)

Info method # 

func (di dirInfo) Info() (FileInfo, error)

IsDir method # 

func (di dirInfo) IsDir() bool

IsDir method #

IsDir reports whether m describes a directory. That is, it tests for the [ModeDir] bit being set in m.

func (m FileMode) IsDir() bool

IsRegular method #

IsRegular reports whether m describes a regular file. That is, it tests that no mode type bits are set.

func (m FileMode) IsRegular() bool

Name method # 

func (di dirInfo) Name() string

Open method # 

func (f *subFS) Open(name string) (File, error)

Perm method #

Perm returns the Unix permission bits in m (m & [ModePerm]).

func (m FileMode) Perm() FileMode

ReadDir method # 

func (f *subFS) ReadDir(name string) ([]DirEntry, error)

ReadDir function #

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 ReadDir(fsys FS, name string) ([]DirEntry, error)

ReadFile method # 

func (f *subFS) ReadFile(name string) ([]byte, error)

ReadFile function #

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 ReadFile(fsys FS, name string) ([]byte, error)

Stat function #

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 Stat(fsys FS, name string) (FileInfo, error)

String method # 

func (m FileMode) String() string

String method # 

func (di dirInfo) String() string

Sub function #

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, 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.

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

Sub method # 

func (f *subFS) Sub(dir string) (FS, error)

Timeout method #

Timeout reports whether this error represents a timeout.

func (e *PathError) Timeout() bool

Type method # 

func (di dirInfo) Type() FileMode

Type method #

Type returns type bits in m (m & [ModeType]).

func (m FileMode) Type() FileMode

Unwrap method # 

func (e *PathError) Unwrap() error

ValidPath function #

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 name "." may be used for the root directory. 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 ValidPath(name string) bool

WalkDir function #

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.

func WalkDir(fsys FS, root string, fn WalkDirFunc) error

cleanGlobPath function #

cleanGlobPath prepares path for glob matching.

func cleanGlobPath(path string) string

errClosed function # 

func errClosed() error

errExist function # 

func errExist() error

errInvalid function # 

func errInvalid() error

errNotExist function # 

func errNotExist() error

errPermission function # 

func errPermission() error

fixErr method #

fixErr shortens any reported names in PathErrors by stripping f.dir.

func (f *subFS) fixErr(err error) error

fullName method #

fullName maps name to the fully-qualified name dir/name.

func (f *subFS) fullName(op string, name string) (string, error)

glob function #

glob searches for files matching pattern in the directory dir and appends them to matches, returning the updated slice. If the directory cannot be opened, glob returns the existing matches. New matches are added in lexicographical order.

func glob(fs FS, dir string, pattern string, matches []string) (m []string, e error)

globWithLimit function # 

func globWithLimit(fsys FS, pattern string, depth int) (matches []string, err error)

hasMeta function #

hasMeta reports whether path contains any of the magic characters recognized by path.Match.

func hasMeta(path string) bool

shorten method #

shorten maps name, which should start with f.dir, back to the suffix after f.dir.

func (f *subFS) shorten(name string) (rel string, ok bool)

walkDir function #

walkDir recursively descends path, calling walkDirFn.

func walkDir(fsys FS, name string, d DirEntry, walkDirFn WalkDirFunc) error

Generated with Arrow