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

ソースコード: 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)

ファイルの形式を記述しているファイルモードの一部 (上記の S_IS*() 関数で使われます) を返します。

通常、ファイルの形式を調べる場合には os.path.is*() 関数を使うことになります; ここで挙げた関数は同じファイルに対して複数のテストを同時に行いたいが、 stat() システムコールを何度も呼び出してオーバヘッドが生じるのを避けたい場合に便利です。これらはまた、ブロック型およびキャラクタ型デバイスに対するテストのように、 os.path で扱うことのできないファイルの情報を調べる際にも便利です。

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

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ノードが存在するデバイス。

該当する 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_COMPRESSED

The file is stored compressed (macOS 10.6+).

stat.UF_HIDDEN

The file should not be displayed in a GUI (macOS 10.5+).

stat.SF_ARCHIVED

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

stat.SF_IMMUTABLE

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

stat.SF_APPEND

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

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

stat.SF_SNAPSHOT

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

See the *BSD or macOS systems man page chflags(2) for more information.

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_MOUNT_POINT

バージョン 3.8 で追加.