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

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 で追加.
