При вызове statx():¶

Для получения состояния файла не требуется иметь права доступа к самому файлу, но в случае указания statx() с путём, потребуются права выполнения (поиска) во всех каталогах, указанных в полном имени файла pathname.

Вызов statx() для определения нужного файла использует pathname, dirfd и flags следующими путями:

Абсолютный путь

Если pathname начинается с косой черты, то целевой файла задан абсолютным путём. В этом случае значение dirfd игнорируется.

Относительный путь

Если pathname начинается не с косой черты и dirfd равно AT_FDCWD, то pathname рассматривается относительно текущего рабочего каталога процесса.

Путь, задаваемый относительно каталога

If pathname is a string that begins with a character other than a slash and dirfd is a file descriptor that refers to a directory, then pathname is a relative pathname that is interpreted relative to the directory referred to by dirfd. (See openat(2) for an explanation of why this is useful.)

По файловому дескриптору

Если значение pathname равно пустой строке и в flags (смотрите ниже) указан флаг AT_EMPTY_PATH, то целевым файлом считается тот, на который указывает файловый дескриптор в dirfd.

Значение flags можно использовать для уточнения поиска на основе пути. Оно составляется из побитно слагаемых следующих констант:

AT_EMPTY_PATH

Если значение pathname равно пустой строке, то вызов выполняет действие с файлом, на который ссылается dirfd (может быть получен с помощью open(2) с флагом O_PATH). В этом случае dirfd может ссылаться на файл любого типа, а не только на каталог.

Если dirfd равно AT_FDCWD, то вызов использует текущий рабочий каталог.

AT_NO_AUTOMOUNT

Don't automount the terminal ("basename") component of pathname if it is a directory that is an automount point. This allows the caller to gather attributes of an automount point (rather than the location it would mount). This flag has no effect if the mount point has already been mounted over.

The AT_NO_AUTOMOUNT flag can be used in tools that scan directories to prevent mass-automounting of a directory of automount points.

All of stat(2), lstat(2), and fstatat(2) act as though AT_NO_AUTOMOUNT was set.

AT_SYMLINK_NOFOLLOW

Если значение pathname является символьной ссылкой, не разыменовывать её, а выдать информацию о самой ссылке, подобно lstat(2).

Значение flags также может использоваться для контроля типа синхронизации, которое выполняет ядро при опросе файла на удалённой файловой системе. Оно составляется из побитно слагаемых следующих значений:

AT_STATX_SYNC_AS_STAT

Работать подобно stat(2). Используется по умолчанию и очень зависит от файловой системы.

AT_STATX_FORCE_SYNC

Принудительно синхронизировать атрибуты с сервером. Может потребовать от сетевой файловой системы выполнить запись данных для получения правильных меток времени.

AT_STATX_DONT_SYNC

Не выполнять синхронизацию, а использовать информацию из кэша (если есть). Это может означать, что полученная информация будет не точна, но в случае с сетевыми файловыми системами это позволяет не обращаться к серверу и даже может быть разрыв соединения.

Аргумент mask в statx() используется для указания ядру какие поля поля нужны вызывающему. Значение mask представляет побитовую комбинацию (посредством OR) следующих констант:

Заметим в общем, что ядро не не отклоняет значения в mask, отличные от вышеперечисленных (исключение из правила смотрите в описании ошибки EINVAL). Вместо этого оно просто информирует вызывающего, какие значения поддерживаются ядром и файловой системой через поле statx.stx_mask. Поэтому не устанавливайте значение mask в UINT_MAX (все биты), так как один или более бит в будущем могут использоваться для указания расширения буфера.

Возвращаемая информация¶

Информация о состоянии целевого файла возвращается в структуре statx, на которую указывает statxbuf. Она содержит stx_mask, в котором описывается возвращённая информация. Значение stx_mask имеет тот же формат, что и аргумент mask, и установленные в нём бит показывают какие поля были заполнены.

Стоит упомянуть, что ядро может вернуть поля, которые не был запрошены и запрошенные поля могут быть не заполнены, в зависимости от поддержки в нижележащей файловой системе (поля, которым были присвоены значение, но которые не были запрошены, можно игнорировать). В этих случаях stx_mask будет не равно mask.

Если файловая система не поддерживает поле или если значение поле содержит непрезентабельное значение (например, файл экзотического типа), то битовая маска в stx_mask, соответствующая этому полю, будет очищена даже если пользователь запросил его, и в целях совместимости в качестве значения, если возможно, будет помещена пустышка (например, в некоторых случаях пустышки UID и GID могут задаваться при монтировании).

Файловая система также может заполнить поля, которые вызывающий не запрашивал, при условии, что их значения доступны и это ничего стоит. Если это выполняется, то будут установлены соответствующие биты в stx_mask.

Замечание: с целью производительности и простоты различные поля в структуре statx могут содержать информацию о состоянии из различных моментов выполнения системного вызова. Например, если изменяется stx_mode или stx_uid другим процессом посредством вызова chmod(2) или chown(2), то stat() может вернуть старое значение stx_mode вместе с новым stx_uid, или старое stx_uid вместе с новым stx_mode.

Помимо полей stx_mask (описанной выше) структура statx имеет следующие поля:

stx_blksize

«Предпочтительный» размер блока для эффективного ввода/вывода в файловой системе (запись в файл более мелкими порциями может привести к неэффективному чтению/изменению/повторной записи).

stx_attributes

Дополнительная информация о состоянии файла (подробности ниже).

stx_nlink

Количество жёстких ссылок на файл.

stx_uid

Пользовательский идентификатор владельца файла.

stx_gid

Групповой идентификатор владельца файла.

stx_mode

Тип файла и режим. Дополнительную информацию смотрите в inode(7).

stx_ino

Номер иноды файла.

stx_size

Размер файла (если он обычный или является символьной ссылкой) в байтах. Размер символьной ссылки равен длине пути файла, на который она ссылается, без конечного нулевого байта.

stx_blocks

Количество блоков (по 512 байт), выделенных для файла на носителе (может быть меньше, чем stx_size/512, когда в файле есть пропуски (holes)).

stx_attributes_mask

Маска, показывающая какие биты в stx_attributes поддерживаются VFS и файловой системой.

stx_atime

Метка времени последнего доступа к файлу.

stx_btime

Метка времени создания файла.

stx_ctime

Метка времени последнего изменения состояния файла.

stx_mtime

Метка времени последнего изменения файла.

stx_dev_major и stx_dev_minor

Устройство, на котором находится файл (инода).

stx_rdev_major и stx_rdev_minor

Устройство, который этот файл (инода) представляет, если файл имеет блочный или символьный тип устройства.

stx_mnt_id

The mount ID of the mount containing the file. This is the same number reported by name_to_handle_at(2) and corresponds to the number in the first field in one of the records in /proc/self/mountinfo.

stx_dio_mem_align

The alignment (in bytes) required for user memory buffers for direct I/O (O_DIRECT) on this file, or 0 if direct I/O is not supported on this file.

STATX_DIOALIGN (stx_dio_mem_align and stx_dio_offset_align) is supported on block devices since Linux 6.1. The support on regular files varies by filesystem; it is supported by ext4, f2fs, and xfs since Linux 6.1.

stx_dio_offset_align

The alignment (in bytes) required for file offsets and I/O segment lengths for direct I/O (O_DIRECT) on this file, or 0 if direct I/O is not supported on this file. This will only be nonzero if stx_dio_mem_align is nonzero, and vice versa.

Дополнительную информацию об этих полях смотрите в inode(7).

Атрибуты файла¶

В поле stx_attributes содержится набор флагов (объединённых через ИЛИ), которые отображают дополнительные атрибуты файла. Заметим, что для атрибута, не указанного как поддерживаемого в stx_attributes_mask, имеющееся здесь значение является не корректным. Биты stx_attributes_mask точно бит в бит соответствуют битам поля stx_attributes.

Флаги:

STATX_ATTR_COMPRESSED

Файл сжат файловой системой и для доступа могут потребоваться дополнительные ресурсы.

STATX_ATTR_IMMUTABLE

Файл невозможно изменить: его нельзя переименовать или удалить, на этот файл нельзя создать жёсткую ссылку и в него нельзя выполнить запись данных. Смотрите chattr(1).

STATX_ATTR_APPEND

Файл может быть открыт только для записи в режиме добавления. Запись в произвольное место не разрешается. Смотрите chattr(1).

STATX_ATTR_NODUMP

Файл не предназначен для резервного копирования программой резервного копирования, например dump(8). Смотрите chattr(1).

STATX_ATTR_ENCRYPTED

Для расшифровки файла файловой системой требуется ключ.

STATX_ATTR_VERITY (начиная с Linux 5.5)

The file has fs-verity enabled. It cannot be written to, and all reads from it will be verified against a cryptographic hash that covers the entire file (e.g., via a Merkle tree).

STATX_ATTR_DAX (начиная с Linux 5.8)

The file is in the DAX (cpu direct access) state. DAX state attempts to minimize software cache effects for both I/O and memory mappings of this file. It requires a file system which has been configured to support DAX.

DAX generally assumes all accesses are via CPU load / store instructions which can minimize overhead for small accesses, but may adversely affect CPU utilization for large transfers.

File I/O is done directly to/from user-space buffers and memory mapped I/O may be performed with direct memory mappings that bypass the kernel page cache.

While the DAX property tends to result in data being transferred synchronously, it does not give the same guarantees as the O_SYNC flag (see open(2)), where data and the necessary metadata are transferred together.

A DAX file may support being mapped with the MAP_SYNC flag, which enables a program to use CPU cache flush instructions to persist CPU store operations without an explicit fsync(2). See mmap(2) for more information.