Пакет fs
Обзор
Пакет fs определяет базовые интерфейсы файловой системы. Файловую систему может предоставлять операционная система узла, а также другие пакеты.
Имена путей
Все интерфейсы в этом пакете используют один и тот же синтаксис имён путей независимо от операционной системы узла.
Имена путей — это последовательности элементов пути в кодировке UTF-8, не являющиеся абсолютными и разделённые косыми чертами, например «x/y/z». Имена путей не должны содержать элементы «.» или «..» либо пустую строку, за исключением особого случая, когда имя "." может использоваться для корневого каталога. Пути не должны начинаться или заканчиваться косой чертой: «/x» и «x/» недопустимы.
Тестирование
См. пакет testing/fstest, который предоставляет средства для тестирования реализаций файловых систем.
Указатель
Файлы пакета
format.go fs.go glob.go readdir.go readfile.go readlink.go stat.go sub.go walk.go
Переменные
Общие ошибки файловой системы. Ошибки, возвращаемые файловыми системами, можно проверять на соответствие этим ошибкам с помощью errors.Is.
var (
ErrInvalid = errInvalid() // "invalid argument"
ErrPermission = errPermission() // "permission denied"
ErrExist = errExist() // "file already exists"
ErrNotExist = errNotExist() // "file does not exist"
) ErrClosed возвращается при попытке выполнить операции с файлом, который уже был закрыт, в том числе при повторном вызове Close.
var ErrClosed = errClosed()
SkipAll используется как возвращаемое значение функции WalkDirFunc, указывающее, что все оставшиеся файлы и каталоги следует пропустить. Ни одна функция не возвращает его в качестве ошибки.
var SkipAll = errors.New("skip everything and stop the walk") SkipDir используется как возвращаемое значение функции WalkDirFunc, указывающее, что каталог, указанный в вызове, следует пропустить. Ни одна функция не возвращает его в качестве ошибки.
var SkipDir = errors.New("skip this directory") func FormatDirEntry 1.21
func FormatDirEntry(dir DirEntry) string
FormatDirEntry возвращает отформатированное представление dir, удобное для чтения. Реализации DirEntry могут вызывать эту функцию из метода String. Результаты для каталога с именем subdir и файла с именем hello.go выглядят так:
d subdir/ - hello.go
func FormatFileInfo 1.21
func FormatFileInfo(info FileInfo) string
FormatFileInfo возвращает отформатированное представление info, удобное для чтения. Реализации FileInfo могут вызывать эту функцию из метода String. Результат для файла с именем "hello.go", размером 100 байт, режимом 0o644, созданного 1 января 1970 года в полдень:
-rw-r--r-- 100 1970-01-01 12:00:00 hello.go
func Glob 1.16
func Glob(fsys FS, pattern string) (matches []string, err error)
Glob возвращает имена всех файлов, соответствующих шаблону, или nil, если совпадений нет. Синтаксис шаблонов совпадает с синтаксисом path.Match. Шаблон может описывать иерархические имена, например usr/*/bin/ed.
Glob игнорирует ошибки файловой системы, например ошибки ввода-вывода при чтении каталогов. Единственная возможная возвращаемая ошибка — path.ErrBadPattern, указывающая на некорректный шаблон.
Если fsys реализует GlobFS, Glob вызывает fsys.Glob. В противном случае Glob использует ReadDir, чтобы обойти дерево каталогов и найти совпадения с шаблоном.
Пример
Код:
fsys := fstest.MapFS{
"file.txt": {},
"file.go": {},
"dir/file.txt": {},
"dir/file.go": {},
"dir/subdir/x.go": {},
}
patterns := []string{
"*.txt",
"*.go",
"dir/*.go",
"dir/*/x.go",
}
for _, pattern := range patterns {
matches, err := fs.Glob(fsys, pattern)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%q matches: %v\n", pattern, matches)
}
Вывод:
"*.txt" matches: [file.txt] "*.go" matches: [file.go] "dir/*.go" matches: [dir/file.go] "dir/*/x.go" matches: [dir/subdir/x.go]
func ReadFile 1.16
func ReadFile(fsys FS, name string) ([]byte, error)
ReadFile считывает указанный файл из файловой системы fsys и возвращает его содержимое. При успешном вызове возвращается ошибка nil, а не io.EOF. (Поскольку ReadFile считывает весь файл, ожидаемый EOF от последнего вызова Read не рассматривается как ошибка, о которой нужно сообщать.)
Если fsys реализует ReadFileFS, ReadFile вызывает fsys.ReadFile. В противном случае ReadFile вызывает fsys.Open и использует Read и Close для возвращённого File.
Пример
Код:
fsys := fstest.MapFS{
"hello.txt": {
Data: []byte("Hello, World!\n"),
},
}
data, err := fs.ReadFile(fsys, "hello.txt")
if err != nil {
log.Fatal(err)
}
fmt.Print(string(data))
Вывод:
Hello, World!
func ReadLink 1.25
func ReadLink(fsys FS, name string) (string, error)
ReadLink возвращает назначение указанной символической ссылки.
Если fsys не реализует ReadLinkFS, ReadLink возвращает ошибку.
func ValidPath 1.16
func ValidPath(name string) bool
ValidPath сообщает, допустимо ли указанное имя пути для использования при вызове Open.
Обратите внимание: во всех системах, включая Windows, пути разделяются косой чертой. Пути, содержащие другие символы, например обратную косую черту и двоеточие, считаются допустимыми, но реализация FS никогда не должна интерпретировать эти символы как разделители элементов пути. Подробнее см. раздел Имена путей.
Пример
Код:
paths := []string{
".",
"x",
"x/y/z",
"",
"..",
"/x",
"x/",
"x//y",
"x/./y",
"x/../y",
}
for _, path := range paths {
fmt.Printf("ValidPath(%q) = %t\n", path, fs.ValidPath(path))
}
Вывод:
ValidPath(".") = true
ValidPath("x") = true
ValidPath("x/y/z") = true
ValidPath("") = false
ValidPath("..") = false
ValidPath("/x") = false
ValidPath("x/") = false
ValidPath("x//y") = false
ValidPath("x/./y") = false
ValidPath("x/../y") = false
func WalkDir 1.16
func WalkDir(fsys FS, root string, fn WalkDirFunc) error
WalkDir обходит дерево файлов, корнем которого является root, вызывая fn для каждого файла или каталога в этом дереве, включая root.
Все ошибки, возникающие при посещении файлов и каталогов, фильтруются функцией fn: подробности см. в документации fs.WalkDirFunc.
Файлы обходятся в лексикографическом порядке, что обеспечивает детерминированный результат, но требует от WalkDir прочитать весь каталог в память, прежде чем продолжить его обход.
WalkDir не переходит по символическим ссылкам, найденным в каталогах, однако, если сам root является символической ссылкой, будет выполнен обход её целевого объекта.
Пример
Код:
root := "/usr/local/go/bin"
fileSystem := os.DirFS(root)
fs.WalkDir(fileSystem, ".", func(path string, d fs.DirEntry, err error) error {
if err != nil {
log.Fatal(err)
}
fmt.Println(path)
return nil
})
type DirEntry 1.16
DirEntry — это запись, прочитанная из каталога (с помощью функции ReadDir или метода ReadDir у ReadDirFile).
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.
// For example, Name would return "hello.go" not "home/gopher/hello.go".
Name() string
// IsDir reports whether the entry describes a directory.
IsDir() bool
// Type returns the type bits for the entry.
// The type bits are a subset of the usual FileMode bits, those returned by the FileMode.Type method.
Type() FileMode
// Info returns the FileInfo for the file or subdirectory described by the entry.
// The returned FileInfo may be from the time of the original directory read
// or from the time of the call to Info. If the file has been removed or renamed
// since the directory read, Info may return an error satisfying errors.Is(err, ErrNotExist).
// If the entry denotes a symbolic link, Info reports the information about the link itself,
// not the link's target.
Info() (FileInfo, error)
} func FileInfoToDirEntry 1.17
func FileInfoToDirEntry(info FileInfo) DirEntry
FileInfoToDirEntry возвращает DirEntry, предоставляющий сведения из info. Если info равен nil, FileInfoToDirEntry возвращает nil.
func ReadDir 1.16
func ReadDir(fsys FS, name string) ([]DirEntry, error)
ReadDir читает указанный каталог и возвращает список записей каталога, отсортированный по имени файла.
Если fsys реализует ReadDirFS, ReadDir вызывает fsys.ReadDir. В противном случае ReadDir вызывает fsys.Open, а затем использует ReadDir и Close для возвращённого ReadDirFile.
type FS 1.16
FS предоставляет доступ к иерархической файловой системе.
Интерфейс FS — это минимальная реализация, необходимая для файловой системы. Файловая система может реализовывать дополнительные интерфейсы, например ReadFileFS, чтобы предоставлять дополнительные или оптимизированные возможности.
testing/fstest.TestFS можно использовать для проверки корректности реализаций FS.
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 the Op field set to "open", the Path field set to name,
// and the Err field describing the problem.
//
// Open should reject attempts to open names that do not satisfy
// ValidPath(name), returning a *PathError with Err set to
// ErrInvalid or ErrNotExist.
Open(name string) (File, error)
} func Sub 1.16
func Sub(fsys FS, dir string) (FS, error)
Sub возвращает FS, соответствующую поддереву, корнем которого является dir в fsys.
Если dir — ".", Sub возвращает fsys без изменений. В противном случае, если fsys реализует SubFS, Sub возвращает fsys.Sub(dir). Иначе Sub возвращает новую реализацию FS sub, которая, по сути, реализует sub.Open(name) как fsys.Open(path.Join(dir, name)). Реализация также соответствующим образом преобразует вызовы ReadDir, ReadFile, ReadLink, Lstat и Glob. Sub не проверяет, существует ли каталог в данный момент.
Обратите внимание, что Sub(os.DirFS("/"), "prefix") эквивалентен os.DirFS("/prefix"), и ни один из этих вариантов не гарантирует, что обращения к операционной системе за пределами "/prefix" будут исключены, поскольку реализация os.DirFS не проверяет наличие внутри "/prefix" символических ссылок, указывающих на другие каталоги. Иными словами, os.DirFS не является универсальной заменой механизма безопасности в стиле chroot, и Sub этого не меняет. Используйте os.Root, чтобы ограничить доступ определёнными деревьями каталогов.
type File 1.16
File предоставляет доступ к одному файлу. Интерфейс File — это минимальная реализация, необходимая для файла. Файлы-каталоги также должны реализовывать ReadDirFile. Для оптимизации файл может реализовывать io.ReaderAt или io.Seeker.
type File interface {
Stat() (FileInfo, error)
Read([]byte) (int, error)
Close() error
} type FileInfo 1.16
FileInfo описывает файл и возвращается функцией Stat.
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
ModTime() time.Time // modification time
IsDir() bool // abbreviation for Mode().IsDir()
Sys() any // underlying data source (can return nil)
} func Lstat 1.25
func Lstat(fsys FS, name string) (FileInfo, error)
Lstat возвращает FileInfo, описывающий указанный файл. Если файл является символической ссылкой, возвращённый FileInfo описывает символическую ссылку. Lstat не пытается перейти по ссылке.
Если fsys не реализует ReadLinkFS, Lstat идентичен Stat.
func Stat 1.16
func Stat(fsys FS, name string) (FileInfo, error)
Stat возвращает FileInfo, описывающий указанный файл в файловой системе.
Если fsys реализует StatFS, Stat вызывает fsys.Stat. В противном случае Stat открывает File, чтобы получить его сведения.
type FileMode 1.16
FileMode представляет режим файла и биты разрешений. Определения битов одинаковы во всех системах, поэтому сведения о файлах можно переносить из одной системы в другую без потери переносимости. Не все биты применимы ко всем системам. Единственный обязательный бит — ModeDir для каталогов.
type FileMode uint32
Определённые биты режима файла являются старшими битами FileMode. Девять младших битов соответствуют стандартным разрешениям Unix rwxrwxrwx. Значения этих битов следует считать частью публичного API; они могут использоваться в сетевых протоколах или представлениях на диске и не должны изменяться, хотя могут быть добавлены новые биты.
const (
// The single letters are the abbreviations
// used by the String method's formatting.
ModeDir FileMode = 1 << (32 - 1 - iota) // d: is a directory
ModeAppend // a: append-only
ModeExclusive // l: exclusive use
ModeTemporary // T: temporary file; Plan 9 only
ModeSymlink // L: symbolic link
ModeDevice // D: device file
ModeNamedPipe // p: named pipe (FIFO)
ModeSocket // S: Unix domain socket
ModeSetuid // u: setuid
ModeSetgid // g: setgid
ModeCharDevice // c: Unix character device, when ModeDevice is set
ModeSticky // t: sticky
ModeIrregular // ?: non-regular file; nothing else is known about this file
// Mask for the type bits. For regular files, none will be set.
ModeType = ModeDir | ModeSymlink | ModeNamedPipe | ModeSocket | ModeDevice | ModeCharDevice | ModeIrregular
ModePerm FileMode = 0777 // Unix permission bits
) func (FileMode) IsDir 1.16
func (m FileMode) IsDir() bool
IsDir сообщает, описывает ли m каталог. Иными словами, функция проверяет, установлен ли в m бит ModeDir.
func (FileMode) IsRegular 1.16
func (m FileMode) IsRegular() bool
IsRegular сообщает, описывает ли m обычный файл. Иными словами, функция проверяет, что ни один из битов типа режима не установлен.
func (FileMode) Perm 1.16
func (m FileMode) Perm() FileMode
Perm возвращает биты разрешений Unix в m (m & ModePerm).
func (FileMode) String 1.16
func (m FileMode) String() string
func (FileMode) Type 1.16
func (m FileMode) Type() FileMode
Type возвращает биты типа в m (m & ModeType).
type GlobFS 1.16
GlobFS — это файловая система с методом Glob.
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)
} type PathError 1.16
PathError содержит сведения об ошибке, операции и пути к файлу, вызвавшем её.
type PathError struct {
Op string
Path string
Err error
}
func (*PathError) Error 1.16
func (e *PathError) Error() string
func (*PathError) Timeout 1.16
func (e *PathError) Timeout() bool
Timeout сообщает, представляет ли эта ошибка тайм-аут.
func (*PathError) Unwrap 1.16
func (e *PathError) Unwrap() error
type ReadDirFS 1.16
ReadDirFS — это интерфейс, реализуемый файловой системой, которая предоставляет оптимизированную реализацию ReadDir.
type ReadDirFS interface {
FS
// ReadDir reads the named directory
// and returns a list of directory entries sorted by filename.
ReadDir(name string) ([]DirEntry, error)
} type ReadDirFile 1.16
ReadDirFile — это файл-каталог, записи которого можно прочитать с помощью метода ReadDir. Каждый файл-каталог должен реализовывать этот интерфейс. (Любой файл может реализовывать этот интерфейс, но в таком случае ReadDir должен возвращать ошибку для файлов, не являющихся каталогами.)
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 yield further DirEntry values.
//
// If n > 0, ReadDir returns at most n DirEntry structures.
// In this case, if ReadDir returns an empty slice, it will return
// a non-nil error explaining why.
// At the end of a directory, the error is io.EOF.
// (ReadDir must return io.EOF itself, not an error wrapping io.EOF.)
//
// If n <= 0, ReadDir returns all remaining DirEntry values from the directory
// in a single slice. In this case, if ReadDir succeeds (reads all the way
// to the end of the directory), it returns the slice and a nil error.
// If it encounters an error before the end of the directory,
// ReadDir returns the DirEntry list read until that point and a non-nil error.
ReadDir(n int) ([]DirEntry, error)
} type ReadFileFS 1.16
ReadFileFS — это интерфейс, реализуемый файловой системой, которая предоставляет оптимизированную реализацию ReadFile.
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 expected EOF
// from the final Read is not treated as an error to be reported.)
//
// The caller is permitted to modify the returned byte slice.
// This method should return a copy of the underlying data.
ReadFile(name string) ([]byte, error)
} type ReadLinkFS 1.25
ReadLinkFS — это интерфейс, реализуемый файловой системой, которая поддерживает чтение символических ссылок.
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)
// 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 there is an error, it should be of type [*PathError].
Lstat(name string) (FileInfo, error)
} type StatFS 1.16
StatFS — это файловая система с методом Stat.
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)
} type SubFS 1.16
SubFS — это файловая система с методом Sub.
type SubFS interface {
FS
// Sub returns an FS corresponding to the subtree rooted at dir.
Sub(dir string) (FS, error)
} type WalkDirFunc 1.16
WalkDirFunc — это тип функции, вызываемой WalkDir для посещения каждого файла или каталога.
Аргумент path содержит аргумент, переданный WalkDir, в качестве префикса. То есть, если WalkDir вызывается с аргументом root "dir" и находит в этом каталоге файл с именем "a", функция обхода будет вызвана с аргументом "dir/a".
Аргумент d — это DirEntry для указанного пути.
Ошибка, возвращаемая функцией, определяет, как WalkDir продолжит работу. Если функция возвращает специальное значение SkipDir, WalkDir пропускает текущий каталог (путь, если d.IsDir() имеет значение true, иначе родительский каталог пути). Если функция возвращает специальное значение SkipAll, WalkDir пропускает все оставшиеся файлы и каталоги. В противном случае, если функция возвращает ненулевую ошибку, WalkDir полностью останавливается и возвращает эту ошибку.
Аргумент err сообщает об ошибке, связанной с путем, указывая, что WalkDir не будет выполнять обход этого каталога. Функция может решить, как обработать эту ошибку; как описано выше, возврат ошибки приведет к остановке обхода всего дерева каталогов функцией WalkDir.
WalkDir вызывает функцию с ненулевым аргументом err в двух случаях.
Во-первых, если первоначальный вызов Stat для корневого каталога завершается ошибкой, WalkDir вызывает функцию, передавая root в качестве path, nil в качестве d и ошибку, полученную от fs.Stat, в качестве err.
Во-вторых, если метод ReadDir каталога (см. ReadDirFile) завершается ошибкой, WalkDir вызывает функцию, передавая путь каталога в качестве path, DirEntry, описывающий каталог, в качестве d и ошибку, полученную от ReadDir, в качестве err. Во втором случае функция вызывается с путем каталога дважды: первый вызов происходит до попытки чтения каталога и получает nil в качестве err, что дает функции возможность вернуть SkipDir или SkipAll и полностью избежать чтения каталога. Второй вызов происходит после неудачного ReadDir и сообщает об ошибке ReadDir. (Если ReadDir завершается успешно, второго вызова не будет.)
Отличия WalkDirFunc от path/filepath.WalkFunc:
- Второй аргумент имеет тип DirEntry, а не FileInfo.
- Функция вызывается до чтения каталога, что позволяет с помощью SkipDir полностью пропустить чтение каталога или с помощью SkipAll пропустить все оставшиеся файлы и каталоги.
- Если чтение каталога завершается ошибкой, функция вызывается для этого каталога второй раз, чтобы сообщить об ошибке.
type WalkDirFunc func(path string, d DirEntry, err error) error
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/io/fs/
