# `stat` --- Interpreting `stat()` results

ソースコード: Lib/stat.py

`stat` モジュールでは、 `os.stat()` 、 `os.lstat()` 、および `os.fstat()` が存在する場合に、これらの関数が返す内容を解釈するための定数や関数を定義しています。 `stat()` 、 `fstat()` 、および `lstat()` の関数呼び出しについての完全な記述はシステムのドキュメントを参照してください。

バージョン 3.4 で変更: stat モジュールは、C 実装に裏付けされるようになりました。

`stat` モジュールでは、特殊なファイル型を判別するための以下の関数を定義しています:

stat.S_ISDIR(mode)

  ファイルのモードがディレクトリの場合にゼロでない値を返します。

stat.S_ISCHR(mode)

  ファイルのモードがキャラクタ型の特殊デバイスファイルの場合にゼロでない値を返します。

stat.S_ISBLK(mode)

  ファイルのモードがブロック型の特殊デバイスファイルの場合にゼロでない値を返します。

stat.S_ISREG(mode)

  ファイルのモードが通常ファイルの場合にゼロでない値を返します。

stat.S_ISFIFO(mode)

  ファイルのモードが FIFO (名前つきパイプ) の場合にゼロでない値を返します。

stat.S_ISLNK(mode)

  ファイルのモードがシンボリックリンクの場合にゼロでない値を返します。

stat.S_ISSOCK(mode)

  ファイルのモードがソケットの場合にゼロでない値を返します。

stat.S_ISDOOR(mode)

  ファイルのモードがドアの場合にゼロでない値を返します。

  バージョン 3.4 で追加.

stat.S_ISPORT(mode)

  ファイルのモードがイベントポートの場合にゼロでない値を返します。

  バージョン 3.4 で追加.

stat.S_ISWHT(mode)

  ファイルのモードがホワイトアウトの場合にゼロでない値を返します。

  バージョン 3.4 で追加.

より一般的なファイルのモードを操作するための二つの関数が定義されています:

stat.S_IMODE(mode)

  `os.chmod()` で設定することのできる一部のファイルモード --- すなわち、ファイルの許可ビット (permission bits) に加え、 (サポートされているシステムでは) スティッキービット (sticky bit)、実行グループ ID 設定 (set-group-id) および実行ユーザ ID 設定 (set-user-id) ビット --- を返します。

stat.S_IFMT(mode)

  Return the portion of the file's mode that describes the file type (used by the `S_IS*()` functions above).

Normally, you would use the `os.path.is*()` functions for testing the type of a file; the functions here are useful when you are doing multiple tests of the same file and wish to avoid the overhead of the `stat()` system call for each test. These are also useful when checking for information about a file that isn't handled by `os.path`, like the tests for block and character devices.

以下はプログラム例です:

    import os, sys
    from stat import *

    def walktree(top, callback):
        '''recursively descend the directory tree rooted at top,
           calling the callback function for each regular file'''

        for f in os.listdir(top):
            pathname = os.path.join(top, f)
            mode = os.lstat(pathname).st_mode
            if S_ISDIR(mode):
                # It's a directory, recurse into it
                walktree(pathname, callback)
            elif S_ISREG(mode):
                # It's a file, call the callback function
                callback(pathname)
            else:
                # Unknown file type, print a message
                print('Skipping %s' % pathname)

    def visitfile(file):
        print('visiting', file)

    if __name__ == '__main__':
        walktree(sys.argv[1], visitfile)

ファイルのモードを人間が可読な文字列に変換するために、追加のユーティリティ関数が提供されています。

stat.filemode(mode)

  ファイルのモードを '-rwxrwxrwx' 形式の文字列に変換します。

  バージョン 3.3 で追加.

  バージョン 3.4 で変更: この関数は、`S_IFDOOR` 、 `S_IFPORT` 、 `S_IFWHT` をサポートしています。

以下の全ての変数は、 `os.stat()` 、 `os.fstat()` 、または `os.lstat()` が返す 10 要素のタプルにおけるインデクスを単にシンボル定数化したものです。

stat.ST_MODE

  Iノードの保護モード。

stat.ST_INO

  Iノード番号。

stat.ST_DEV

  Iノードが存在するデバイス。

stat.ST_NLINK

  該当する Iノードへのリンク数。

stat.ST_UID

  ファイルの所持者のユーザ ID。

stat.ST_GID

  ファイルの所持者のグループ ID。

stat.ST_SIZE

  通常ファイルではバイトサイズ; いくつかの特殊ファイルでは処理待ちのデータ量。

stat.ST_ATIME

  最後にアクセスした時刻。

stat.ST_MTIME

  最後に変更された時刻。

stat.ST_CTIME

  オペレーティングシステムから返される"ctime"。あるOS(Unixなど)では最後にメタデータが更新された時間となり、別のOS(Windowsなど)では作成時間となります(詳細については各プラットフォームのドキュメントを参照してください)。

"ファイルサイズ" の解釈はファイルの型によって異なります。通常のファイルの場合、サイズはファイルの大きさをバイトで表したものです。ほとんどの Unix 系 (特に Linux) における FIFO やソケットの場合、"サイズ" は `os.stat()` 、 `os.fstat()` 、あるいは `os.lstat()` を呼び出した時点で読み出し待ちであったデータのバイト数になります; この値は時に有用で、特に上記の特殊なファイルを非ブロックモードで開いた後にポーリングを行いたいといった場合に便利です。他のキャラクタ型およびブロック型デバイスにおけるサイズフィールドの意味はさらに異なっていて、背後のシステムコールの実装によります。

以下の変数は、 `ST_MODE` フィールドで使用されるフラグを定義しています。

最初に挙げる、以下のフラグを使うよりは、上記の関数を使うほうがポータブルです:

stat.S_IFSOCK

  ソケット。

stat.S_IFLNK

  シンボリックリンク。

stat.S_IFREG

  通常のファイル。

stat.S_IFBLK

  ブロックデバイス。

stat.S_IFDIR

  ディレクトリ。

stat.S_IFCHR

  キャラクターデバイス。

stat.S_IFIFO

  FIFO。

stat.S_IFDOOR

  ドア。

  バージョン 3.4 で追加.

stat.S_IFPORT

  イベントポート。

  バージョン 3.4 で追加.

stat.S_IFWHT

  ホワイトアウト。

  バージョン 3.4 で追加.

注釈

`S_IFDOOR` 、 `S_IFPORT` 、または `S_IFWHT` は、プラットフォームがこれらのファイルタイプをサポートしていない場合、0 として定義されます。

以下のフラグは、 `os.chmod()` の mode 引数に使うこともできます:

stat.S_ISUID

  UID ビットを設定する。

stat.S_ISGID

  グループIDビットを設定する。このビットには幾つかの特殊ケースがあります。ディレクトリに対して設定されていた場合、 BSD のセマンティクスが利用される事を示しています。すなわち、そこに作成されるファイルは、作成したプロセスの有効グループID (effective group ID) ではなくそのディレクトリのグループIDを継承し、そこに作成されるディレクトリにも `S_ISGID` ビットが設定されます。グループ実行ビット (`S_IXGRP`) が設定されていないファイルに対してこのビットが設定されていた場合、強制ファイル/レコードロックを意味します (`S_ENFMT` も参照してください)。

stat.S_ISVTX

  スティッキービット。このビットがディレクトリに対して設定されているとき、そのディレクトリ内のファイルは、そのファイルのオーナー、あるいはそのディレクトリのオーナーか特権プロセスのみが、リネームや削除をすることが出来ることを意味しています。

stat.S_IRWXU

  ファイルオーナーの権限に対するマスク。

stat.S_IRUSR

  オーナーがリード権限を持っている。

stat.S_IWUSR

  オーナーがライト権限を持っている。

stat.S_IXUSR

  オーナーが実行権限を持っている。

stat.S_IRWXG

  グループの権限に対するマスク。

stat.S_IRGRP

  グループがリード権限を持っている。

stat.S_IWGRP

  グループがライト権限を持っている。

stat.S_IXGRP

  グループが実行権限を持っている。

stat.S_IRWXO

  その他 (グループ外) の権限に対するマスク。

stat.S_IROTH

  その他はリード権限を持っている。

stat.S_IWOTH

  その他はライト権限を持っている。

stat.S_IXOTH

  その他は実行権限を持っている。

stat.S_ENFMT

  System V ファイルロック強制。このフラグは `S_ISGID` と共有されています。グループ実行ビット (`S_IXGRP`) が設定されていないファイルでは、ファイル/レコードのロックが強制されます。

stat.S_IREAD

  `S_IRUSR` の、 Unix V7 のシノニム。

stat.S_IWRITE

  `S_IWUSR` の、 Unix V7 のシノニム。

stat.S_IEXEC

  `S_IXUSR` の、 Unix V7 のシノニム。

以下のフラグを `os.chflags()` の flags 引数として利用できます:

stat.UF_NODUMP

  ファイルをダンプしない。

stat.UF_IMMUTABLE

  ファイルは変更されない。

stat.UF_APPEND

  ファイルは追記しかされない。

stat.UF_OPAQUE

  ユニオンファイルシステムのスタックを通したとき、このディレクトリは不透明です。

stat.UF_NOUNLINK

  ファイルはリネームや削除されない。

stat.UF_COMPRESSED

  ファイルは圧縮して保存される (macOS 10.6+)。

stat.UF_HIDDEN

  ファイルは GUI で表示されるべきでない (macOS 10.5+)。

stat.SF_ARCHIVED

  ファイルはアーカイブされているかもしれません。

stat.SF_IMMUTABLE

  ファイルは変更されない。

stat.SF_APPEND

  ファイルは追記しかされない。

stat.SF_NOUNLINK

  ファイルはリネームや削除されない。

stat.SF_SNAPSHOT

  このファイルはスナップショットファイルです。

詳しい情報は *BSD か macOS システムの man page chflags(2) を参照してください。

Windows では、`os.stat()` が返す `st_file_attributes` メンバー内のビットを検証する際に、以下のファイル属性定数を使用できます。これらの定数の意味について詳しくは、Windows API documentation を参照してください。

stat.FILE_ATTRIBUTE_ARCHIVE
stat.FILE_ATTRIBUTE_COMPRESSED
stat.FILE_ATTRIBUTE_DEVICE
stat.FILE_ATTRIBUTE_DIRECTORY
stat.FILE_ATTRIBUTE_ENCRYPTED
stat.FILE_ATTRIBUTE_HIDDEN
stat.FILE_ATTRIBUTE_INTEGRITY_STREAM
stat.FILE_ATTRIBUTE_NORMAL
stat.FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
stat.FILE_ATTRIBUTE_NO_SCRUB_DATA
stat.FILE_ATTRIBUTE_OFFLINE
stat.FILE_ATTRIBUTE_READONLY
stat.FILE_ATTRIBUTE_REPARSE_POINT
stat.FILE_ATTRIBUTE_SPARSE_FILE
stat.FILE_ATTRIBUTE_SYSTEM
stat.FILE_ATTRIBUTE_TEMPORARY
stat.FILE_ATTRIBUTE_VIRTUAL

  バージョン 3.5 で追加.

Windows では、`os.lstat()` が返す `st_reparse_tag` メンバーとの比較に次の定数が 使えます。 これらはよく知られている定数ですが、全てを網羅したリストではありません。

stat.IO_REPARSE_TAG_SYMLINK
stat.IO_REPARSE_TAG_MOUNT_POINT
stat.IO_REPARSE_TAG_APPEXECLINK

  バージョン 3.8 で追加.