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

Бит set-UID.

stat.S_ISGID

Бит set-group-ID. Этот бит имеет несколько специальных назначений. Для каталога он указывает, что для этого каталога используются семантики BSD: созданные в нём файлы наследуют идентификатор группы каталога, а не эффективный идентификатор группы создавшего их процесса; созданные в нём каталоги также получают установленный бит S_ISGID. Для файла, у которого не установлен бит выполнения для группы (S_IXGRP), бит set-group-ID указывает на обязательную блокировку файлов и записей (см. также S_ENFMT).

stat.S_ISVTX

Бит sticky. Если этот бит установлен для каталога, файл в этом каталоге может быть переименован или удалён только его владельцем, владельцем каталога или привилегированным процессом.

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.

Следующие флаги можно использовать в аргументе 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

Файл является firmlink (macOS 10.15+).

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

stat.SF_DATALESS

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

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

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

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

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.