Documentation
¶
Overview ¶
Package fsはファイルシステムへの基本的なインターフェースを定義します。 ファイルシステムはホストオペレーティングシステムだけでなく、他のパッケージによっても提供されることがあります。
Index ¶
- Variables
- func FormatDirEntry(dir DirEntry) string
- func FormatFileInfo(info FileInfo) string
- func Glob(fsys FS, pattern string) (matches []string, err error)
- func ReadFile(fsys FS, name string) ([]byte, error)
- func ValidPath(name string) bool
- func WalkDir(fsys FS, root string, fn WalkDirFunc) error
- type DirEntry
- type FS
- type File
- type FileInfo
- type FileMode
- type GlobFS
- type PathError
- type ReadDirFS
- type ReadDirFile
- type ReadFileFS
- type StatFS
- type SubFS
- type WalkDirFunc
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalid = errInvalid() ErrPermission = errPermission() ErrExist = errExist() ErrNotExist = errNotExist() ErrClosed = errClosed() )
汎用ファイルシステムのエラー。 ファイルシステムから返されるエラーは、これらのエラーと比較してテストすることができます errors.Is を使用して。
var SkipAll = errors.New("skip everything and stop the walk")
SkipAllは、WalkDirFuncsからの返り値として使用され、残りのすべてのファイルとディレクトリをスキップすることを示します。これは、どの関数からもエラーとして返されません。
var SkipDir = errors.New("skip this directory")
SkipDirはWalkDirFuncsからの戻り値として使用され、呼び出しで指定されたディレクトリがスキップされることを示します。これは、どの関数からもエラーとして返されません。
Functions ¶
func FormatDirEntry ¶ added in v1.21.0
FormatDirEntry は dir の人間が読みやすい形式のフォーマット済みバージョンを返します。 DirEntry の実装は、これを String メソッドから呼び出すことができます。 名前が subdir のディレクトリと名前が hello.go のファイルの出力は次の通りです：
d subdir/ - hello.go
func FormatFileInfo ¶ added in v1.21.0
FormatFileInfoは、人間が読みやすい形式に整形されたinfoのバージョンを返します。 FileInfoの実装は、Stringメソッドからこれを呼び出すことができます。 "hello.go"という名前のファイル、100バイト、モード0o644、作成日時は1970年1月1日の正午の場合、出力は次のようになります。
-rw-r--r-- 100 1970-01-01 12:00:00 hello.go
func Glob ¶
Globは、パターンに一致するすべてのファイルの名前を返します。一致するファイルがない場合はnilを返します。 パターンの構文はpath.Matchと同じです。パターンはusr/*/bin/edのような階層的な名前を指定することができます。
Globは、ディレクトリの読み取り時のI/Oエラーなどのファイルシステムのエラーを無視します。 返される唯一の可能なエラーは、path.ErrBadPatternで、パターンが不正であることを報告します。
もしfsがGlobFSを実装している場合、Globはfs.Globを呼び出します。 そうでない場合、Globはディレクトリツリーをトラバースし、パターンに一致するものを探します。
func ReadFile ¶
ReadFileはファイルシステムfsから指定された名前のファイルを読み込み、その内容を返します。 成功した呼び出しはnilのエラーを返しますが、io.EOFではありません。 (ReadFileはファイル全体を読み込むため、最後のReadでの予想されるEOFはエラーとして報告されません。)
もしfsがReadFileFSを実装している場合、ReadFileはfs.ReadFileを呼び出します。 そうでなければ、ReadFileはfs.Openを呼び出し、返されたファイルに対してReadとCloseを使用します。
func ValidPath ¶
ValidPathは与えられたパス名がOpenの呼び出しに使用するために有効かどうかを報告します。
Openに渡されるパス名はUTF-8でエンコードされた、ルートなしのスラッシュで区切られたパス要素のシーケンス（例: "x/y/z"）です。 パス名には、"."または".."または空の文字列を含めることはできませんが、ルートディレクトリが "."という特殊なケースを除いてはです。 パスはスラッシュで始まることや終わることはできません: "/x"や"x/"は無効です。
なお、パスは全てのシステムでスラッシュで区切られます（Windowsでも）。 バックスラッシュやコロンなどの他の文字を含むパスも有効ですが、これらの文字は実装によっては絶対にパス要素の区切りとして解釈されるべきではありません。
func WalkDir ¶
func WalkDir(fsys FS, root string, fn WalkDirFunc) error
WalkDirはルートにルートされたファイルツリーを走査し、各ファイルまたはディレクトリに対してfnを呼び出します。
ファイルとディレクトリを訪れる中で発生するエラーは、fnによってフィルタリングされます： 詳細については、fs.WalkDirFuncのドキュメントを参照してください。
ファイルは辞書式順に走査されますが、出力を決定論的にするために、WalkDirはディレクトリ全体をメモリに読み込んでから、そのディレクトリを走査する必要があります。
WalkDirはディレクトリ内で見つかったシンボリックリンクをたどりませんが、ルート自体がシンボリックリンクであれば、その対象が走査されます。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/io/fs"
"github.com/shogo82148/std/log"
"github.com/shogo82148/std/os"
)
func main() {
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
})
}
Output:
Types ¶
type DirEntry ¶
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)
}
DirEntryはディレクトリから読み取られたエントリです (ReadDir関数やReadDirFileのReadDirメソッドを使用して)。
func FileInfoToDirEntry ¶ added in v1.17.0
FileInfoToDirEntryは、infoから情報を返すDirEntryを返します。 もしinfoがnilの場合、FileInfoToDirEntryはnilを返します。
type 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)
}
FSは階層的なファイルシステムへのアクセスを提供します。
FSインターフェースはファイルシステムに必要な最小限の実装です。 ファイルシステムは追加のインターフェース、例えばReadFileFSを実装することができます。 追加の機能や最適化された機能を提供することができます。
func Sub ¶
Subはfsysのdirでルートされた部分木に対応するFSを返します。
dirが"."の場合、Subはfsysを変更せずに返します。 そうでない場合、fsがSubFSを実装している場合、Subはfsys.Sub(dir)を返します。 そうでない場合、Subは効果的に、sub.Open(name)をfsys.Open(path.Join(dir, name))として実装する新しいFS実装subを返します。 実装では、ReadDir、ReadFile、そしてGlobへの呼び出しも適切に変換されます。
os.DirFS("/prefix")とSub(os.DirFS("/"), "prefix")は同等であることに注意してください。 どちらも、"/prefix"の外部にあるオペレーティングシステムのアクセスを回避することを保証するものではありません。 なぜなら、os.DirFSの実装は、"/prefix"内部の他のディレクトリを指すシンボリックリンクをチェックしないためです。 つまり、os.DirFSはchrootスタイルのセキュリティメカニズムの一般的な代替手段ではなく、Subもその事実を変えません。
type File ¶
Fileは単一のファイルへのアクセスを提供します。 Fileインターフェースはファイルに必要な最小限の実装です。 ディレクトリファイルはReadDirFileも実装する必要があります。 ファイルは最適化としてio.ReaderAtまたはio.Seekerを実装する場合があります。
type FileInfo ¶
type FileInfo interface {
Name() string
Size() int64
Mode() FileMode
ModTime() time.Time
IsDir() bool
Sys() any
}
FileInfoはファイルを説明し、Statによって返されます。
type FileMode ¶
type FileMode uint32
FileModeはファイルのモードとパーミッションビットを表します。 ビットの定義はすべてのシステムで同じであるため、 ファイルに関する情報をポータブルに他のシステムに移動することができます。 すべてのビットがすべてのシステムに適用されるわけではありません。 ディレクトリに対してはModeDirのみが必須です。
const ( // 単一の文字は、Stringメソッドのフォーマットで使用される省略形です。 ModeDir FileMode = 1 << (32 - 1 - iota) ModeAppend ModeExclusive ModeTemporary ModeSymlink ModeDevice ModeNamedPipe ModeSocket ModeSetuid ModeSetgid ModeCharDevice ModeSticky ModeIrregular // タイプビットのマスク。通常のファイルでは、全く設定されません。 ModeType = ModeDir | ModeSymlink | ModeNamedPipe | ModeSocket | ModeDevice | ModeCharDevice | ModeIrregular ModePerm FileMode = 0777 )
定義されたファイルモードビットは、FileModeの最も重要なビットです。 9つの最も下位のビットは、標準のUnixのrwxrwxrwx権限です。 これらのビットの値は、パブリックAPIの一部と見なされ、 ワイヤープロトコルやディスク表現で使用される可能性があります。 これらのビットは変更しないでくださいが、新しいビットが追加されることはあります。
type GlobFS ¶
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)
}
GlobFSはGlobメソッドを持つファイルシステムです。
type ReadDirFS ¶
type ReadDirFS interface {
FS
// ReadDir reads the named directory
// and returns a list of directory entries sorted by filename.
ReadDir(name string) ([]DirEntry, error)
}
ReadDirFSは、ReadDirの最適化された実装を提供するファイルシステムで実装されるインターフェースです。
type ReadDirFile ¶
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)
}
ReadDirFileは、ReadDirメソッドを使用してエントリを読み取ることができるディレクトリファイルです。 すべてのディレクトリファイルは、このインターフェースを実装する必要があります。 （任意のファイルがこのインターフェースを実装することも許可されていますが、非ディレクトリの場合はReadDirがエラーを返すべきです。）
type ReadFileFS ¶
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)
}
ReadFileFSは、ReadFileの最適化された実装を提供するファイルシステムによって実装されるインターフェースです。
type StatFS ¶
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)
}
StatFSは、Statメソッドを持つファイルシステムです。
type SubFS ¶
type SubFS interface {
FS
// Sub returns an FS corresponding to the subtree rooted at dir.
Sub(dir string) (FS, error)
}
SubFSはSubメソッドを持つファイルシステムです。
type WalkDirFunc ¶
WalkDirFuncはWalkDirによって各ファイルやディレクトリを訪れるために呼び出される関数の型です。
path引数には、WalkDirの引数としてのパスが前置されます。 つまり、root引数が "dir" でWalkDirがそのディレクトリで "a" という名前のファイルを見つけた場合、 引数が "dir/a" であるように歩行関数が呼び出されます。
d引数は、指定されたパスのfs.DirEntryです。
関数によって返されるエラー結果は、WalkDirの進行方法を制御します。 関数が特別な値SkipDirを返す場合、WalkDirは現在のディレクトリをスキップします（d.IsDir()がtrueであればパス、 そうでなければパスの親ディレクトリ）。 関数が特別な値SkipAllを返す場合、WalkDirは残りのすべてのファイルおよびディレクトリをスキップします。 それ以外の場合、関数が非nilのエラーを返す場合、WalkDirは完全に停止し、そのエラーを返します。
エラー引数は、パスに関連するエラーを報告し、WalkDirがそのディレクトリに入ろうとしないことを示します。 関数はそのエラーを処理する方法を決定することができます。 エラーを返すと、WalkDirは木全体のツリーをかけるのをやめます。
WalkDirは、2つのケースで非nilのerr引数を持って関数を呼び出します。
まず、ルートディレクトリの初期fs.Statが失敗した場合、WalkDirは関数をpathがrootに設定され、 dがnilに設定され、errがfs.Statからのエラーに設定された状態で呼び出します。
2番目に、ディレクトリのReadDirメソッドが失敗した場合、WalkDirは関数をディレクトリのパスがpathに設定され、 dがディレクトリを記述するfs.DirEntryに設定され、errがReadDirからのエラーに設定された状態で呼び出します。 この2番目の場合、関数はディレクトリのパスで2回呼び出されます。 最初の呼び出しは、ディレクトリの読み取りが試みられる前で、errがnilに設定されるため、関数にSkipDirまたはSkipAllを返すチャンスがあり、ReadDirを完全に回避します。 2回目の呼び出しは、失敗したReadDirからのエラーを報告します。 （ReadDirが成功すると、2回目の呼び出しがありません。）
WalkDirFuncとfilepath.WalkFuncの違いは次のとおりです：
- 2番目の引数の型がfs.DirEntryであること。
- ディレクトリを読み取る前に関数が呼び出され、SkipDirまたはSkipAllがディレクトリの読み取りを完全にバイパスしたり、 残りのすべてのファイルとディレクトリをスキップしたりするようにすること。
- ディレクトリの読み取りが失敗した場合、そのディレクトリについてのエラーを報告するために、関数が2回呼び出されること。
Source Files