fs

package
v1.25.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2025 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

fsパッケージはファイルシステムへの基本的なインターフェースを定義します。 ファイルシステムはホストオペレーティングシステムだけでなく、他のパッケージによっても提供されることがあります。

ファイルシステムの実装のテストを支援するための testing/fstest パッケージを参照してください。

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalid    = errInvalid()
	ErrPermission = errPermission()
	ErrExist      = errExist()
	ErrNotExist   = errNotExist()
	ErrClosed     = errClosed()
)

汎用ファイルシステムのエラー。 ファイルシステムから返されるエラーは、これらのエラーと比較してテストすることができます errors.Is を使用して。

View Source 
var SkipAll = errors.New("skip everything and stop the walk")

SkipAllは、WalkDirFunc からの戻り値として使用され、 残りのすべてのファイルとディレクトリをスキップすることを示します。 これはどの関数からもエラーとして返されません。

View Source 
var SkipDir = errors.New("skip this directory")

SkipDirは、WalkDirFunc からの戻り値として使用され、 呼び出しで名前が付けられたディレクトリをスキップすることを示します。 これはどの関数からもエラーとして返されません。

Functions

func FormatDirEntry added in v1.21.0 

func FormatDirEntry(dir DirEntry) string

FormatDirEntry は dir の人間が読みやすい形式のフォーマット済みバージョンを返します。 DirEntry の実装は、これを String メソッドから呼び出すことができます。 名前が subdir のディレクトリと名前が hello.go のファイルの出力は次の通りです：

d subdir/ - hello.go

func FormatFileInfo added in v1.21.0 

func FormatFileInfo(info FileInfo) string

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 

func Glob(fsys FS, pattern string) (matches []string, err error)

Globは、パターンに一致するすべてのファイルの名前を返します。一致するファイルがない場合はnilを返します。 パターンの構文は path.Match と同じです。パターンはusr/*/bin/edのような階層的な名前を指定することができます。

Globは、ディレクトリの読み取り時のI/Oエラーなどのファイルシステムのエラーを無視します。 返される唯一の可能なエラーは、 path.ErrBadPattern で、パターンが不正であることを報告します。

もしfsが GlobFS を実装している場合、Globはfs.Globを呼び出します。 そうでない場合、Globは ReadDir を使用してディレクトリツリーをトラバースし、パターンに一致するものを探します。

Example 
package main

import (
	"github.com/shogo82148/std/fmt"
	"github.com/shogo82148/std/io/fs"
	"github.com/shogo82148/std/log"
	"github.com/shogo82148/std/testing/fstest"
)

func main() {
	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)
	}

}

Output:
"*.txt" matches: [file.txt]
"*.go" matches: [file.go]
"dir/*.go" matches: [dir/file.go]
"dir/*/x.go" matches: [dir/subdir/x.go]

func ReadFile 

func ReadFile(fsys FS, name string) ([]byte, error)

ReadFileはファイルシステムfsから指定された名前のファイルを読み込み、その内容を返します。 成功した呼び出しはnilのエラーを返しますが、io.EOF ではありません。 (ReadFileはファイル全体を読み込むため、最後のReadでの予想されるEOFはエラーとして報告されません。)

もしfsが ReadFileFS を実装している場合、ReadFileはfs.ReadFileを呼び出します。 そうでなければ、ReadFileはfs.Openを呼び出し、返された File に対してReadとCloseを使用します。

Example 
package main

import (
	"github.com/shogo82148/std/fmt"
	"github.com/shogo82148/std/io/fs"
	"github.com/shogo82148/std/log"
	"github.com/shogo82148/std/testing/fstest"
)

func main() {
	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))

}

Output:
Hello, World!

func ReadLink(fsys FS, name string) (string, error)

ReadLink returns the destination of the named symbolic link.

If fsys does not implement ReadLinkFS, then ReadLink returns an error.

func ValidPath 

func ValidPath(name string) bool

ValidPathは与えられたパス名がOpenの呼び出しに使用するために有効かどうかを報告します。

openに渡されるパス名は、UTF-8エンコードされた、 ルートを持たない、スラッシュで区切られたパス要素のシーケンスです。例："x/y/z"。 パス名には"."や".."または空文字列の要素を含んではいけません。 ただし、特別なケースとして、ルートディレクトリには"."という名前を使用できます。 パスはスラッシュで始まったり終わったりしてはいけません："/x"や"x/"は無効です。

なお、パスは全てのシステムでスラッシュで区切られます（Windowsでも）。 バックスラッシュやコロンなどの他の文字を含むパスも有効ですが、これらの文字は FS の実装によっては絶対にパス要素の区切りとして解釈されるべきではありません。

Example 
package main

import (
	"github.com/shogo82148/std/fmt"
	"github.com/shogo82148/std/io/fs"
)

func main() {
	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))
	}

}

Output:
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 

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
	})
}

Types

type DirEntry 

type DirEntry interface {
	Name() string

	IsDir() bool

	Type() FileMode

	Info() (FileInfo, error)
}

DirEntryはディレクトリから読み取られたエントリです (ReadDir 関数や ReadDirFile のReadDirメソッドを使用して)。

func FileInfoToDirEntry added in v1.17.0 

func FileInfoToDirEntry(info FileInfo) DirEntry

FileInfoToDirEntryは、infoから情報を返す DirEntry を返します。 もしinfoがnilの場合、FileInfoToDirEntryはnilを返します。

func ReadDir 

func ReadDir(fsys FS, name string) ([]DirEntry, error)

ReadDirは指定されたディレクトリを読み取り、 ファイル名でソートされたディレクトリエントリのリストを返します。

fsが ReadDirFS を実装している場合、ReadDirはfs.ReadDirを呼び出します。 そうでない場合、ReadDirはfs.Openを呼び出し、返されたファイルでReadDirとCloseを使用します。

type FS 

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

FSは階層的なファイルシステムへのアクセスを提供します。

FSインターフェースはファイルシステムに必要な最小限の実装です。 ファイルシステムは追加のインターフェース、例えば ReadFileFS を実装することができます。 追加の機能や最適化された機能を提供することができます。

testing/fstest.TestFS は、FSの実装の正確さをテストするために使用できます。

func Sub 

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

Subはfsysのdirでルートされた部分木に対応する FS を返します。

dirが"."の場合、Subはfsysを変更せずに返します。 そうでなければ、fsが SubFS を実装している場合、Subはfsys.Sub(dir)を返します。 そうでなければ、Subは新しい FS 実装subを返します。これは 実質的にsub.Open(name)をfsys.Open(path.Join(dir, name))として実装します。 この実装はまた、ReadDir、ReadFile、 ReadLink、Lstat、およびGlobの呼び出しも適切に変換します。

os.DirFS("/prefix")とSub(os.DirFS("/"), "prefix")は同等であることに注意してください。 どちらも、"/prefix"の外部にあるオペレーティングシステムのアクセスを回避することを保証するものではありません。 なぜなら、 os.DirFS の実装は、"/prefix"内部の他のディレクトリを指すシンボリックリンクをチェックしないためです。 つまり、os.DirFSはchrootスタイルのセキュリティメカニズムの一般的な代替手段ではなく、Subもその事実を変えません。

type File 

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

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 によって返されます。

func Lstat added in v1.25.0 

func Lstat(fsys FS, name string) (FileInfo, 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 fsys does not implement ReadLinkFS, then Lstat is identical to Stat.

func Stat 

func Stat(fsys FS, name string) (FileInfo, error)

Statはファイルシステムから指定されたファイルに関する FileInfo を返します。

もしfsが StatFS を実装している場合、Statはfs.Statを呼び出します。 そうでない場合、Statは File を開いて統計情報を取得します。

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の一部と見なされ、 ワイヤープロトコルやディスク表現で使用される可能性があります。 これらのビットは変更しないでくださいが、新しいビットが追加されることはあります。

func (FileMode) IsDir 

func (m FileMode) IsDir() bool

IsDirはmがディレクトリを記述しているかどうかを報告します。 つまり、m内の ModeDir ビットがセットされているかどうかをテストします。

func (FileMode) IsRegular 

func (m FileMode) IsRegular() bool

IsRegularはmが正規のファイルを記述しているかどうかを報告します。 つまり、モードのタイプビットが設定されていないかどうかをテストします。

func (FileMode) Perm 

func (m FileMode) Perm() FileMode

Permは、m（m＆ModePerm）のUnixパーミッションビットを返します。

func (FileMode) String 

func (m FileMode) String() string

func (FileMode) Type 

func (m FileMode) Type() FileMode

Typeはm（m＆ModeType）のタイプビットを返します。

type GlobFS 

type GlobFS interface {
	FS

	Glob(pattern string) ([]string, error)
}

GlobFSはGlobメソッドを持つファイルシステムです。

type PathError 

type PathError struct {
	Op   string
	Path string
	Err  error
}

PathErrorはエラーとそれを引き起こした操作とファイルパスを記録します。

func (*PathError) Error 

func (e *PathError) Error() string

func (*PathError) Timeout 

func (e *PathError) Timeout() bool

Timeoutは、このエラーがタイムアウトを示すかどうかを報告します。

func (*PathError) Unwrap 

func (e *PathError) Unwrap() error

type ReadDirFS 

type ReadDirFS interface {
	FS

	ReadDir(name string) ([]DirEntry, error)
}

ReadDirFSは、 ReadDir の最適化された実装を提供するファイルシステムで実装されるインターフェースです。

type ReadDirFile 

type ReadDirFile interface {
	File

	ReadDir(n int) ([]DirEntry, error)
}

ReadDirFileは、ReadDirメソッドを使用してエントリを読み取ることができるディレクトリファイルです。 すべてのディレクトリファイルは、このインターフェースを実装する必要があります。 （任意のファイルがこのインターフェースを実装することも許可されていますが、非ディレクトリの場合はReadDirがエラーを返すべきです。）

type ReadFileFS 

type ReadFileFS interface {
	FS

	ReadFile(name string) ([]byte, error)
}

ReadFileFSは、 ReadFile の最適化された実装を提供するファイルシステムによって実装されるインターフェースです。

type ReadLinkFS added in v1.25.0 

type ReadLinkFS interface {
	FS

	ReadLink(name string) (string, error)

	Lstat(name string) (FileInfo, error)
}

ReadLinkFS is the interface implemented by a file system that supports reading symbolic links.

type StatFS 

type StatFS interface {
	FS

	Stat(name string) (FileInfo, error)
}

StatFSは、Statメソッドを持つファイルシステムです。

type SubFS 

type SubFS interface {
	FS

	Sub(dir string) (FS, error)
}

SubFSはSubメソッドを持つファイルシステムです。

type WalkDirFunc 

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

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引数を持って関数を呼び出します。

まず、ルートディレクトリの初期 Stat が失敗した場合、WalkDirは関数をpathがrootに設定され、 dがnilに設定され、errが fs.Stat からのエラーに設定された状態で呼び出します。

2番目に、ディレクトリのReadDirメソッド（ ReadDirFile を参照）が失敗した場合、WalkDirは関数をディレクトリのパスがpathに設定され、 dがディレクトリを記述する DirEntry に設定され、errがReadDirからのエラーに設定された状態で呼び出します。 この2番目の場合、関数はディレクトリのパスで2回呼び出されます。 最初の呼び出しは、ディレクトリの読み取りが試みられる前で、errがnilに設定されるため、関数に SkipDir または SkipAll を返すチャンスがあり、ReadDirを完全に回避します。 2回目の呼び出しは、失敗したReadDirからのエラーを報告します。 （ReadDirが成功すると、2回目の呼び出しがありません。）

WalkDirFuncと path/filepath.WalkFunc の違いは次のとおりです：

  • 2番目の引数の型が FileInfo ではなく DirEntry であること。
  • ディレクトリを読み取る前に関数が呼び出され、 SkipDir または SkipAll がディレクトリの読み取りを完全にバイパスしたり、 残りのすべてのファイルとディレクトリをスキップしたりするようにすること。
  • ディレクトリの読み取りが失敗した場合、そのディレクトリについてのエラーを報告するために、関数が2回呼び出されること。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.