| statx(2) | System Calls Manual | statx(2) |
statx - считывает состояние файла (расширенный вариант)
Стандартная библиотека языка C (libc, -lc)
#define _GNU_SOURCE /* Смотрите feature_test_macros(7) */ #include <fcntl.h> /* Определение констант AT_* */ #include <sys/stat.h>
int statx(int dirfd, const char *restrict pathname, int flags,
unsigned int mask, struct statx *restrict statxbuf);
Этот системный вызов возвращает информацию о файле, записывая её в буфер, на который указывает statxbuf. Возвращаемый буфер представляет собой структуру следующего вида:
struct statx {
__u32 stx_mask; /* Mask of bits indicating
filled fields */
__u32 stx_blksize; /* Block size for filesystem I/O */
__u64 stx_attributes; /* Extra file attribute indicators */
__u32 stx_nlink; /* Number of hard links */
__u32 stx_uid; /* User ID of owner */
__u32 stx_gid; /* Group ID of owner */
__u16 stx_mode; /* File type and mode */
__u64 stx_ino; /* Inode number */
__u64 stx_size; /* Total size in bytes */
__u64 stx_blocks; /* Number of 512B blocks allocated */
__u64 stx_attributes_mask;
/* Mask to show what's supported
in stx_attributes */
/* The following fields are file timestamps */
struct statx_timestamp stx_atime; /* Last access */
struct statx_timestamp stx_btime; /* Creation */
struct statx_timestamp stx_ctime; /* Last status change */
struct statx_timestamp stx_mtime; /* Last modification */
/* If this file represents a device, then the next two
fields contain the ID of the device */
__u32 stx_rdev_major; /* Major ID */
__u32 stx_rdev_minor; /* Minor ID */
/* The next two fields contain the ID of the device
containing the filesystem where the file resides */
__u32 stx_dev_major; /* Major ID */
__u32 stx_dev_minor; /* Minor ID */
__u64 stx_mnt_id; /* Mount ID */
/* Direct I/O alignment restrictions */
__u32 stx_dio_mem_align;
__u32 stx_dio_offset_align;
};
Метки времени файла хранятся в структуре следующего вида:
struct statx_timestamp {
__s64 tv_sec; /* количество секунд с начала Эпохи (время UNIX) */
__u32 tv_nsec; /* количество наносекунд, начиная с tv_sec */
};
(зарезервированное пространство и заполнители не показаны)
Для получения состояния файла не требуется иметь права доступа к самому файлу, но в случае указания statx() с путём, потребуются права выполнения (поиска) во всех каталогах, указанных в полном имени файла pathname.
Вызов statx() для определения нужного файла использует pathname, dirfd и flags следующими путями:
Значение flags можно использовать для уточнения поиска на основе пути. Оно составляется из побитно слагаемых следующих констант:
Значение flags также может использоваться для контроля типа синхронизации, которое выполняет ядро при опросе файла на удалённой файловой системе. Оно составляется из побитно слагаемых следующих значений:
Аргумент mask в statx() используется для указания ядру какие поля поля нужны вызывающему. Значение mask представляет побитовую комбинацию (посредством OR) следующих констант:
| STATX_TYPE | Требуется stx_mode & S_IFMT |
| STATX_MODE | Want 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 | The same as STATX_BASIC_STATS | STATX_BTIME. |
| It is deprecated and should not be used. | |
| STATX_MNT_ID | Want stx_mnt_id (since Linux 5.8) |
| STATX_DIOALIGN | Want stx_dio_mem_align and stx_dio_offset_align |
| (since Linux 6.1; support varies by filesystem) |
Заметим в общем, что ядро не не отклоняет значения в 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 имеет следующие поля:
Дополнительную информацию об этих полях смотрите в inode(7).
В поле stx_attributes содержится набор флагов (объединённых через ИЛИ), которые отображают дополнительные атрибуты файла. Заметим, что для атрибута, не указанного как поддерживаемого в stx_attributes_mask, имеющееся здесь значение является не корректным. Биты stx_attributes_mask точно бит в бит соответствуют битам поля stx_attributes.
Флаги:
При успешном выполнении возвращается 0. При ошибке возвращается -1, а в errno содержится код ошибки.
Linux.
Linux 4.11, glibc 2.28.
ls(1), stat(1), access(2), chmod(2), chown(2), name_to_handle_at(2), readlink(2), stat(2), utime(2), proc(5), capabilities(7), inode(7), symlink(7)
Русский перевод этой страницы руководства разработал(и) Alexander Golubev <fatzer2@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Hotellook, Nikita <zxcvbnm3230@mail.ru>, Spiros Georgaras <sng@hellug.gr>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru>, Иван Павлов <pavia00@gmail.com> и Kirill Rekhov <krekhov.dev@gmail.com>
Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.
Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков.
| 2 мая 2024 г. | Справочные страницы Linux 6.9.1 |