"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.
