stat — 解释 stat() 结果 Source code: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)
如果模式来自门，则返回非零。
在 3.4 版本中添加。
stat.S_ISPORT(mode)
如果模式来自事件端口，则返回非零。
在 3.4 版本中添加。
stat.S_ISWHT(mode)
如果模式来自白茫茫一片，则返回非零。
在 3.4 版本中添加。
定义了两个附加函数用于更广泛地操作文件模式：
stat.S_IMODE(mode)
返回可由 os.chmod() 设置的文件模式部分 - 即文件的权限位，加上粘滞位、设置组 ID 和设置用户 ID 位（在支持它们的系统上）。
stat.S_IFMT(mode)
返回描述文件类型的文件模式部分（由上面的 S_IS*() 函数使用）。
通常，您会使用 os.path.is*() 函数来测试文件的类型；当您对同一文件进行多次测试并希望避免每次测试的 stat() 系统调用开销时，此处的函数非常有用。在检查 os.path 未处理的文件信息时，这些函数也很有用，例如块设备和字符设备的测试。
Example:
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):
# 这是一个目录，递归进入它
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”形式的字符串。
在 3.3 版本中添加。
在 3.4 版更改: 该函数支持 S_IFDOOR , S_IFPORT 和 S_IFWHT 。
下面的所有变量都只是 os.stat() 、 os.fstat() 或 os.lstat() 返回的十元组的符号索引。
stat.ST_MODE
Inode 保护模式。
stat.ST_INO
Inode number.
stat.ST_DEV
设备 inode 驻留在。
stat.ST_NLINK
指向 inode 的链接数。
stat.ST_UID
所有者的用户 ID。
stat.ST_GID
所有者的群组 ID。
stat.ST_SIZE
普通文件的大小（以字节为单位）；等待某些特殊文件的数据量。
stat.ST_ATIME
上次访问的时间。
stat.ST_MTIME
最后修改时间。
stat.ST_CTIME
操作系统报告的“ctime”。在某些系统（如 Unix）上，它是上次元数据更改的时间；而在其他系统（如 Windows）上，它是创建时间（有关详细信息，请参阅平台文档）。
“文件大小”的解释根据文件类型而变化。对于普通文件，这是文件的大小（以字节为单位）。对于大多数 Unix 版本（尤其是 Linux）下的 FIFO 和套接字，“大小”是在调用 os.stat() 、 os.fstat() 或 os.lstat() 时等待读取的字节数；这有时很有用，尤其是在非阻塞打开后轮询这些特殊文件之一时。其他字符和块设备的大小字段含义差异更大，具体取决于底层系统调用的实现。
下面的变量定义了 ST_MODE 字段中使用的标志。
使用上述函数比使用第一组标志更具可移植性：
stat.S_IFSOCK
Socket.
stat.S_IFLNK
Symbolic link.
stat.S_IFREG
Regular file.
stat.S_IFBLK
Block device.
stat.S_IFDIR
Directory.
stat.S_IFCHR
Character device.
stat.S_IFIFO
FIFO.
stat.S_IFDOOR
Door.
在 3.4 版本中添加。
stat.S_IFPORT
Event port.
在 3.4 版本中添加。
stat.S_IFWHT
Whiteout.
在 3.4 版本中添加。
Note
当平台不支持这些文件类型时， S_IFDOOR 、 S_IFPORT 或 S_IFWHT 被定义为 0。
os.chmod() 的模式参数中还可以使用以下标志：
stat.S_ISUID
设置 UID 位。
stat.S_ISGID
设置组 ID 位。此位有几种特殊用途。对于目录，它表示将对该目录使用 BSD 语义：在该目录中创建的文件从目录继承其组 ID，而不是从创建进程的有效组 ID 继承，并且在该目录中创建的目录也将获得 S_ISGID 位设置。对于未设置组执行位 ( S_IXGRP ) 的文件，设置组 ID 位表示强制文件/记录锁定（另请参阅 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
Unix V7 中 S_IRUSR 的同义词。
stat.S_IWRITE
Unix V7 中 S_IWUSR 的同义词。
stat.S_IEXEC
Unix V7 中 S_IXUSR 的同义词。
os.chflags() 的 flags 参数中可以使用以下标志：
stat.UF_SETTABLE
所有用户可设置的标志。
在 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)
在 3.13 版本中添加。
stat.UF_DATAVAULT
该文件需要读取或写入的权限（macOS 10.13+）
在 3.13 版本中添加。
stat.UF_HIDDEN
该文件不应显示在 GUI (macOS 10.5+) 中。
stat.SF_SETTABLE
所有超级用户可更改的标志
在 3.13 版本中添加。
stat.SF_SUPPORTED
所有超级用户支持的标志
Availability: macOS
在 3.13 版本中添加。
stat.SF_SYNTHETIC
所有超级用户只读合成标志
Availability: macOS
在 3.13 版本中添加。
stat.SF_ARCHIVED
该文件可能会被存档。
stat.SF_IMMUTABLE
该文件不得被更改。
stat.SF_APPEND
该文件仅可附加。
stat.SF_RESTRICTED
该文件需要有写入权限（macOS 10.13+）
在 3.13 版本中添加。
stat.SF_NOUNLINK
该文件不能被重命名或删除。
stat.SF_SNAPSHOT
该文件是一个快照文件。
stat.SF_FIRMLINK
该文件是 Firmlink（macOS 10.15+）
在 3.13 版本中添加。
stat.SF_DATALESS
该文件是无数据对象（macOS 10.15+）
在 3.13 版本中添加。
有关更多信息，请参阅 *BSD 或 macOS 系统手册页 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 版本中添加。
© 2001–2025 Python 软件基金会根据 PSF 许可授权。
https://docs.python.org/3.13/library/stat.html