ИМЯ

statx - считывает состояние файла (расширенный вариант)

ОБЗОР

#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <fcntl.h>           /* константы AT_* */

int statx(int dirfd, const char *pathname, int flags,
          unsigned int mask, struct statx *statxbuf);

ОПИСАНИЕ

Этот системный вызов возвращает информацию о файле, записывая её в буфер, на который указывает statxbuf. Возвращаемый буфер представляет собой структуру следующего вида:

struct statx {

    __u32 stx_mask;        /* маска битов, показывающая

                              заполненные поля */

    __u32 stx_blksize;     /* размер блока ввода-вывода файловой системы */

    __u64 stx_attributes;  /* индикаторы дополнительных файловых атрибутов */

    __u32 stx_nlink;       /* количество жёстких ссылок */

    __u32 stx_uid;         /* идентификатор пользователя-владельца */

    __u32 stx_gid;         /* идентификатор группы-владельца */

    __u16 stx_mode;        /* тип файла и режим доступа */

    __u64 stx_ino;         /* номер иноды */

    __u64 stx_size;        /* полный размер в байтах */

    __u64 stx_blocks;      /* количество выделенных 512-байтовых блоков */

    __u64 stx_attributes_mask;

                           /* маска, показывающая поддерживаемые атрибуты

                              в stx_attributes */

    /* поля меток времени */

    struct statx_timestamp stx_atime;  /* последний доступ */

    struct statx_timestamp stx_btime;  /* создание */

    struct statx_timestamp stx_ctime;  /* последнее изменение состояния */

    struct statx_timestamp stx_mtime;  /* последнее изменение */

    /* если файл представляет устройство, то в следующих

       полях содержится идентификатор устройства */

    __u32 stx_rdev_major;  /* основной идентификатор */

    __u32 stx_rdev_minor;  /* дополнительный идентификатор */

    /* поля идентификатора устройства с файловой системой,

       в которой содержится файл */

    __u32 stx_dev_major;   /* основной идентификатор */

    __u32 stx_dev_minor;   /* дополнительный идентификатор */
};

Метки времени файла хранятся в структуре следующего вида:

struct statx_timestamp {

    __s64 tv_sec;    /* количество секунд с начала Эпохи (время UNIX) */

    __u32 tv_nsec;   /* количество наносекунд, начиная с tv_sec */
};

(зарезервированное пространство и заполнители не показаны)

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

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

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

Абсолютный путь: Если pathname начинается с косой черты, то целевой файла задан абсолютным путём. В этом случае значение dirfd игнорируется.
Относительный путь: Если pathname начинается не с косой черты и dirfd равно AT_FDCWD, то pathname рассматривается относительно текущего рабочего каталога процесса.
Путь, задаваемый относительно каталога: Если pathname начинается не с косой черты и dirfd содержит файловый дескриптор, указывающий на каталог, то pathname рассматривается относительно каталога, на который ссылается dirfd.
По файловому дескриптору: Если значение pathname равно пустой строке и в flags (смотрите ниже) указан флаг AT_EMPTY_PATH, то целевым файлом считается тот, на который указывает файловый дескриптор в dirfd.

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

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

: Если dirfd равно AT_FDCWD, то вызов использует текущий рабочий каталог.
: Данный флаг существует только в Linux; для его получения определите _GNU_SOURCE.

AT_NO_AUTOMOUNT: Не выполнять автоматическое монтирование конечного компонента («basename») pathname, если это каталог, который является точкой монтирования. Это позволяет вызывающему получить атрибуты точки монтирования (а не расположения, где её предполагалось смонтировать). Этот флаг можно использовать в инструментах, сканирующих каталоги, для предотвращения массового автоматического монтирования каталогов в их точки монтирования. Флаг AT_NO_AUTOMOUNT не учитывается, если к точке уже уже была выполнено монтирование. Этот флаг есть только Linux; для его получения нужно задать _GNU_SOURCE.
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) следующих констант:

STATX_TYPE	Требуется stx_mode & S_IFMT
STATX_MODE	Требуется stx_mode & ~S_IFMT
STATX_NLINK	Требуется stx_nlink
STATX_UID	Требуется stx_uid
STATX_GID	Требуется stx_gid
STATX_ATIME	Требуется stx_atime
STATX_MTIME	Требуется stx_mtime
STATX_CTIME	Требуется stx_ctime
STATX_INO	Требуется stx_ino
STATX_SIZE	Требуется stx_size
STATX_BLOCKS	Требуется stx_blocks
STATX_BASIC_STATS	[всё вышеперечисленное]
STATX_BTIME	Требуется stx_btime
STATX_ALL	[все доступные в данный момент поля]

Заметим, что ядро не не отклоняет значения в mask, отличные от вышеперечисленных. Вместо этого оно просто информирует вызывающего, какие значения поддерживаются ядром и файловой системой через поле 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: Устройство, который этот файл (инода) представляет, если файл имеет блочный или символьный тип устройства.

Дополнительную информацию об этих полях смотрите в 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: Для расшифровки файла файловой системой требуется ключ.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

При успешном выполнении возвращается 0. В случае ошибки возвращается -1, а errno устанавливается в соответствующее значение.

ОШИБКИ

EACCES: Запрещён поиск в одном из каталогов пути pathname (смотрите также path_resolution(7)).
EBADF: Значение dirfd не является правильным открытым файловым дескриптором.
EFAULT: Значение pathname или statxbuf равно NULL или указывает на расположение вне доступного процессу адресного пространства.
EINVAL: Указано неверное значение в flags.
EINVAL: В mask указан зарезервированный флаг.
ELOOP: Во время определения пути встретилось слишком много символьных ссылок.
ENAMETOOLONG: Слишком длинное значение аргумента pathname.
ENOENT: Компонент пути pathname не существует или в pathname указана пустая строка и в flags не указан AT_EMPTY_PATH.
ENOMEM: Не хватает памяти (например, памяти ядра).
ENOTDIR: Компонент префикса пути pathname содержит относительный путь и dirfd содержит файловый дескриптор, указывающий на файл, а не на каталог.

ВЕРСИИ

Вызов statx() был добавлен в Linux 4.11; поддержка в glibc доступна с версии 2.28.

СООТВЕТСТВИЕ СТАНДАРТАМ

Вызов statx() есть только в Linux.

ИМЯ