Пакет fs
Обзор
Пакет fs определяет базовые интерфейсы для файловой системы. Файловая система может предоставляться операционной системой хоста, а также другими пакетами.
См. пакет testing/fstest для поддержки тестирования реализаций файловых систем.
Индекс
Примеры
Файлы пакета
format.go fs.go glob.go readdir.go readfile.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 = errClosed() // "file already closed"
) 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, сообщая, что шаблон имеет неправильный формат.
Если fs реализует GlobFS, Glob вызывает fs.Glob. В противном случае Glob использует ReadDir для обхода дерева каталогов и поиска соответствий шаблону.
func ReadFile 1.16
func ReadFile(fsys FS, name string) ([]byte, error)
ReadFile считывает указанный файл из файловой системы fs и возвращает его содержимое. Успешный вызов возвращает ошибку nil, а не io.EOF. (Поскольку ReadFile считывает весь файл, ожидаемый EOF от последнего считывания не обрабатывается как ошибка, подлежащая сообщению.)
Если fs реализует ReadFileFS, ReadFile вызывает fs.ReadFile. В противном случае ReadFile вызывает fs.Open и использует Read и Close для возвращенного File.
func ValidPath 1.16
func ValidPath(name string) bool
ValidPath сообщает, является ли данное имя пути допустимым для использования в вызове Open.
Имена путей, передаваемые в open, закодированы в UTF-8, не содержат корень, представляют собой разделяемые слешами последовательности элементов пути, такие как «x/y/z». Имена путей не должны содержать элемент «.» или «..» или пустую строку, за исключением специального случая, когда корневой каталог имеет имя «.». Пути не должны начинаться или заканчиваться слешем: «/x» и «x/» недопустимы.
Обратите внимание, что пути разделяются слешами на всех системах, даже Windows. Пути, содержащие другие символы, такие как обратный слеш и двоеточие, принимаются как допустимые, но эти символы никогда не должны интерпретироваться реализацией FS как разделители элементов пути.
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
})
тип 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 считывает указанный каталог и возвращает отсортированный по имени файла список записей каталога.
Если fs реализует ReadDirFS, ReadDir вызывает fs.ReadDir. В противном случае ReadDir вызывает fs.Open и использует ReadDir и Close для возвращенного файла.
тип FS 1.16
FS предоставляет доступ к иерархической файловой системе.
Интерфейс FS — это минимальная реализация, необходимая для файловой системы. Файловая система может реализовывать дополнительные интерфейсы, такие как ReadFileFS, чтобы предоставить дополнительную или оптимизированную функциональность.
testing/fstest.TestFS может использоваться для проверки реализаций FS на корректность.
type FS interface {
// Open opens the named file.
//
// 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 без изменений. В противном случае, если fs реализует SubFS, Sub возвращает fsys.Sub(dir). В противном случае Sub возвращает новую реализацию FS под названием sub, которая фактически реализует sub.Open(name) как fsys.Open(path.Join(dir, name)). Реализация также переводит вызовы ReadDir, ReadFile и Glob соответствующим образом.
Обратите внимание, что Sub(os.DirFS("/"), "prefix") эквивалентно os.DirFS("/prefix") и ни один из них не гарантирует избежания доступа к операционной системе за пределами "/prefix", поскольку реализация os.DirFS не проверяет символические ссылки внутри "/prefix", которые указывают на другие каталоги. То есть os.DirFS не является универсальной заменой механизма безопасности типа chroot, и Sub не меняет этот факт.
тип File 1.16
File предоставляет доступ к одному файлу. Интерфейс File — это минимальная реализация, необходимая для файла. Файлы каталогов также должны реализовывать ReadDirFile. Файл может реализовывать io.ReaderAt или io.Seeker для оптимизации.
type File interface {
Stat() (FileInfo, error)
Read([]byte) (int, error)
Close() error
} тип 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 Stat 1.16
func Stat(fsys FS, name string) (FileInfo, error)
Stat возвращает FileInfo, описывающий указанный файл из файловой системы.
Если fs реализует StatFS, Stat вызывает fs.Stat. В противном случае Stat открывает File для его статуса.
тип 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 каталог. То есть он проверяет, установлен ли бит ModeDir в m.
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 the 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 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 вызван с корневым аргументом "dir" и находит файл с именем "a" в этом каталоге, функция walk будет вызвана с аргументом "dir/a".
Аргумент d — это DirEntry для указанного пути.
Результат ошибки, возвращаемый функцией, управляет тем, как WalkDir продолжает выполнение. Если функция возвращает специальное значение SkipDir, WalkDir пропускает текущий каталог (путь, если d.IsDir() истинно, в противном случае родительский каталог пути). Если функция возвращает специальное значение SkipAll, WalkDir пропускает все оставшиеся файлы и каталоги. В противном случае, если функция возвращает не-nil ошибку, WalkDir останавливается полностью и возвращает эту ошибку.
Аргумент err сообщает об ошибке, связанной с путём, сигнализируя о том, что WalkDir не войдёт в этот каталог. Функция может решить, как обработать эту ошибку; как описано ранее, возвращение ошибки заставит WalkDir прекратить обход всей древовидной структуры.
WalkDir вызывает функцию с ненулевым аргументом err в двух случаях.
Во-первых, если первоначальное Stat в корневом каталоге терпит неудачу, WalkDir вызывает функцию с путём, установленным в корень, d, установленным в nil, и err, установленным в ошибку из fs.Stat.
Во-вторых, если метод ReadDir каталога (см. ReadDirFile) терпит неудачу, WalkDir вызывает функцию с путём, установленным в путь каталога, d, установленным в DirEntry, описывающим каталог, и err, установленным в ошибку из ReadDir. В этом втором случае функция вызывается дважды с путём каталога: первый вызов происходит до попытки чтения каталога и имеет err, установленным в nil, давая функции возможность вернуть 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/
