stat — Интерпретация результатов stat()

Исходный код: Lib/stat.py

Модуль stat определяет константы и функции для интерпретации результатов вызовов os.stat(), os.fstat() и os.lstat() (если они существуют). Для получения полной информации о вызовах stat(), fstat() и lstat() обратитесь к документации вашей системы.

Модуль 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)

Возвращает ненулевое значение, если режим соответствует файлу «whiteout».

Добавлена в версии 3.4.

Определены две дополнительные функции для более общего управления режимом файла:

stat.S_IMODE(mode)

Возвращает часть режима файла, которая может быть изменена с помощью os.chmod() — биты разрешений файла, а также биты «sticky», «set-group-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.

Все переменные ниже представляют собой просто символические индексы в 10-кортеже, возвращаемом функциями os.stat(), os.fstat() или os.lstat().

stat.ST_MODE

Режим защиты индексного узла.

stat.ST_INO

Номер индексного узла.

stat.ST_DEV

Устройство, на котором расположен индексный узел.

stat.ST_NLINK

Количество ссылок на индексный узел.

stat.ST_UID

Идентификатор пользователя владельца.

stat.ST_GID

Идентификатор группы владельца.

stat.ST_SIZE

Размер обычного файла в байтах; количество данных, ожидающих обработки в некоторых специальных файлах.

stat.ST_ATIME

Время последнего доступа.

stat.ST_MTIME

Время последней модификации.

stat.ST_CTIME

Поле «ctime», возвращаемое операционной системой. В некоторых системах (например, Unix) это время последнего изменения метаданных, а в других (например, Windows) — время создания (см. документацию платформы для получения подробностей).

Интерпретация «размера файла» изменяется в зависимости от типа файла. Для обычных файлов это размер файла в байтах. Для FIFO и сокетов в большинстве версий Unix (включая Linux), «размер» — это количество байтов, ожидающих чтения во время вызова 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

Файл «whiteout».

Добавлена в версии 3.4.

Следующие флаги также могут быть использованы в аргументе mode функции os.chmod():

stat.S_ISUID

Бит установки UID.

stat.S_ISGID

Флаг «установить группу». Этот флаг имеет несколько специальных применений. Для каталога он указывает на использование семантики BSD: файлы, созданные в этом каталоге, наследуют идентификатор группы из каталога, а не из эффективного идентификатора группы процесса, создавшего файл, и созданные в нём каталоги также получат флаг 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

Синоним Unix V7 для S_IRUSR.

stat.S_IWRITE

Синоним Unix V7 для S_IWUSR.

stat.S_IEXEC

Синоним Unix V7 для S_IXUSR.

Следующие флаги могут быть использованы в аргументе flags функции os.chflags():

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

Используется для обработки идентификаторов документов (macOS)

Добавлен в версии 3.13.

stat.UF_DATAVAULT

Для чтения или записи файла требуется разрешение (macOS 10.13+)

Добавлен в версии 3.13.

stat.UF_HIDDEN

Файл не должен отображаться в графическом интерфейсе (macOS 10.5+).

stat.SF_SETTABLE

Все изменяемые суперпользователем флаги

Добавлен в версии 3.13.

stat.SF_SUPPORTED

Все поддерживаемые суперпользователем флаги

Доступность: macOS

Добавлен в версии 3.13.

stat.SF_SYNTHETIC

Все синтетические флаги, только для чтения суперпользователем

Доступность: 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

Файл является символической ссылкой (macOS 10.15+)

Добавлен в версии 3.13.

stat.SF_DATALESS

Файл является объектом без данных (macOS 10.15+)

Добавлен в версии 3.13.

См. страницу руководства *BSD или macOS систем chflags(2) для получения дополнительной информации.

В Windows доступны следующие константы атрибутов файлов для проверки битов в элементе st_file_attributes , возвращаемом функцией os.stat(). См. документацию API Windows для получения дополнительной информации о значении этих констант.

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 доступны следующие константы для сравнения со значением члена st_reparse_tag возвращённого функцией os.lstat(). Это известные константы, но не исчерпывающий список.

stat.IO_REPARSE_TAG_SYMLINK

stat.IO_REPARSE_TAG_MOUNT_POINT

stat.IO_REPARSE_TAG_APPEXECLINK

Добавлен в версии 3.8.