`stat` --- `stat()` の結果を解釈する¶

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

stat モジュールは、os.stat()、os.fstat()、os.lstat() (利用できる場合) の結果を解釈するための定数と関数を定義します。 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)¶: ファイルのモードがドアの場合にゼロでない値を返します。

Added in version 3.4.

stat.S_ISPORT(mode)¶: ファイルのモードがイベントポートの場合にゼロでない値を返します。

Added in version 3.4.

stat.S_ISWHT(mode)¶: ファイルのモードがホワイトアウトの場合にゼロでない値を返します。

Added in version 3.4.

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

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

stat.S_IFMT(mode)¶: ファイルのモードのうち、ファイル種別を表す部分を返します (上述の S_IS*() 関数で使われます)。

通常、ファイル種別の判定には os.path.is*() 関数を使います。同じファイルに対して複数の判定を行い、そのたびに stat() システムコールを呼び出すオーバーヘッドを避けたい場合は、このモジュールの関数が役立ちます。また、ブロックデバイスやキャラクターデバイスかどうかなど、os.path が扱わないファイル情報を調べる場合にも便利です。

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

import os, sys
from stat import *

def walktree(top, callback):
    '''top をルートとするディレクトリツリーを再帰的にたどり、
       通常のファイルごとにコールバック関数を呼び出す'''

    for f in os.listdir(top):
        pathname = os.path.join(top, f)
        mode = os.lstat(pathname).st_mode
        if S_ISDIR(mode):
            # ディレクトリなら再帰的にたどる
            walktree(pathname, callback)
        elif S_ISREG(mode):
            # ファイルならコールバック関数を呼び出す
            callback(pathname)
        else:
            # 不明なファイル種別ならメッセージを表示する
            print('Skipping %s' % pathname)

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

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

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

stat.filemode(mode)¶: ファイルのモードを '-rwxrwxrwx' 形式の文字列に変換します。

Added in version 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¶: ドア。

Added in version 3.4.

stat.S_IFPORT¶: イベントポート。

Added in version 3.4.

stat.S_IFWHT¶: ホワイトアウト。

Added in version 3.4.

注釈

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

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

stat.S_ISUID¶: set-user-ID ビット。

stat.S_ISGID¶: set-group-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_SETTABLE¶: ユーザーが設定できるすべてのフラグ。

Added in version 3.13.

stat.UF_NODUMP¶: ファイルをダンプしない。

stat.UF_IMMUTABLE¶: ファイルを変更してはいけない。

stat.UF_APPEND¶: ファイルへの追記だけを許可する。

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

stat.UF_NOUNLINK¶: ファイル名の変更や削除を禁止する。

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

stat.UF_TRACKED¶: ドキュメント ID の処理に使う (macOS)。

Added in version 3.13.

stat.UF_DATAVAULT¶: ファイルの読み書きにエンタイトルメントが必要 (macOS 10.13+)。

Added in version 3.13.

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

stat.SF_SETTABLE¶: スーパーユーザーが変更できるすべてのフラグ。

Added in version 3.13.

stat.SF_SUPPORTED¶: スーパーユーザーが利用できるすべてのフラグ。

利用可能な環境: macOS

Added in version 3.13.

stat.SF_SYNTHETIC¶: スーパーユーザー用の、読み取り専用の合成フラグすべて。

利用可能な環境: macOS

Added in version 3.13.

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

stat.SF_IMMUTABLE¶: ファイルを変更してはいけない。

stat.SF_APPEND¶: ファイルへの追記だけを許可する。

stat.SF_RESTRICTED¶: ファイルへの書き込みにエンタイトルメントが必要 (macOS 10.13+)。

Added in version 3.13.

stat.SF_NOUNLINK¶: ファイル名の変更や削除を禁止する。

stat.SF_SNAPSHOT¶: このファイルはスナップショットファイルです。

stat.SF_FIRMLINK¶: ファイルが firmlink である (macOS 10.15+)。

Added in version 3.13.

stat.SF_DATALESS¶: ファイルがデータを持たないオブジェクトである (macOS 10.15+)。

Added in version 3.13.

詳しい情報は *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¶: Added in version 3.5.

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

stat.IO_REPARSE_TAG_SYMLINK¶
stat.IO_REPARSE_TAG_MOUNT_POINT¶
stat.IO_REPARSE_TAG_APPEXECLINK¶: Added in version 3.8.

Linux では、os.statx() が返す stx_attributes メンバーと stx_attributes_mask メンバーのビットを調べるために、以下のファイル属性定数を利用できます。各定数の意味の詳細は statx(2) のマニュアルページを参照してください。

stat.STATX_ATTR_COMPRESSED¶
stat.STATX_ATTR_IMMUTABLE¶
stat.STATX_ATTR_APPEND¶
stat.STATX_ATTR_NODUMP¶
stat.STATX_ATTR_ENCRYPTED¶
stat.STATX_ATTR_AUTOMOUNT¶
stat.STATX_ATTR_MOUNT_ROOT¶
stat.STATX_ATTR_VERITY¶
stat.STATX_ATTR_DAX¶
stat.STATX_ATTR_WRITE_ATOMIC¶: Added in version 3.15.

`stat` --- `stat()` の結果を解釈する¶

前のトピックへ

次のトピックへ

このページ

stat --- stat() の結果を解釈する¶

`stat` --- `stat()` の結果を解釈する¶