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 で追加.
以下の全ての変数は、 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 で追加.
以下のフラグは、 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) が設定されていないファイルでは、ファイル/レコードのロックが強制されます。
以下のフラグを 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 メンバーとの比較に次の定数が 使えます。
これらはよく知られている定数ですが、全てを網羅したリストではありません。