Provided by: manpages-ru-dev_4.27.0-1_all 
НАИМЕНОВАНИЕ
utimensat, futimens - изменение временных меток файла с наносекундной точностью
БИБЛИОТЕКА
Стандартная библиотека языка C (libc, -lc)
ОБЗОР
#include <fcntl.h> /* определения констант AT_* */
#include <sys/stat.h>
int utimensat(int dirfd, const char *pathname,
const struct timespec times[_Nullable 2], int flags);
int futimens(int fd, const struct timespec times[_Nullable 2]);
Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):
utimensat():
Начиная с glibc 2.10:
_POSIX_C_SOURCE >= 200809L
До glibc 2.10:
_ATFILE_SOURCE
futimens():
Начиная с glibc 2.10:
_POSIX_C_SOURCE >= 200809L
До glibc 2.10:
_BSD_SOURCE
ОПИСАНИЕ
Вызовы utimensat() и futimens() обновляют временные метки файла с наносекундной точностью. Этим они
отличаются от utime(2) и utimes(2), которые имеют секундную и микросекундную точность, соответственно.
В вызове utimensat() файл задаётся в pathname по имени. В вызове futimens() файл указывается в виде
открытого файлового дескриптора в fd.
For both calls, the new file timestamps are specified in the array times: times[0] specifies the new
"last access time" (atime); times[1] specifies the new "last modification time" (mtime). Each of the
elements of times specifies a time as the number of seconds and nanoseconds since the Epoch, 1970-01-01
00:00:00 +0000 (UTC). This information is conveyed in a timespec(3) structure.
Обновлённые временные метки файла устанавливаются в самое большое значение, поддерживаемое файловой
системой, но не больше чем указанное время.
Если в поле tv_nsec одной из структур timespec указано специальное значение UTIME_NOW, то соответствующая
временная метка файла устанавливается в значение текущего времени. Если в поле tv_nsec одной из структур
timespec указано специальное значение UTIME_OMIT, то соответствующая временная метка файла не изменяется.
В обоих случаях значение поля tv_sec игнорируется.
Если значение times равно NULL, то значение обеих временных меток становится равным текущему времени.
The status change time (ctime) will be set to the current time, even if the other time stamps don't
actually change.
Права доступа
Чтобы установить временные метки файла равными текущему времени (т.е., значение times равно NULL, или оба
значения поля tv_nsec равно UTIME_NOW) требуется одно из:
• вызывающий должен иметь право на запись в файл;
• эффективный пользовательский идентификатор вызывающего должен совпадать с идентификатором владельца
файла;
• вызывающий должен иметь соответствующие права.
Чтобы установить временные метки файла равными не текущему времени (т. е., значение times не равно NULL,
или оба значения поля tv_nsec не равны UTIME_NOW или UTIME_OMIT) требуется выполнение условия 2 или 3.
Если в обоих значениях поле tv_nsec равно UTIME_OMIT, то проверки владения файлом и права доступа к нему
не выполняются, и временные метки файла не изменяются, но всё равно могут проверяться другие условия
возникновения ошибок.
Особенности utimensat()
Если в pathname указано относительное значение имени, то по умолчанию оно отсчитывается от каталога, на
который ссылается открытый файловый дескриптор, dirfd (а не от текущего рабочего каталога вызывающего
процесса, как это делается в utimes(2) для относительных имён). В openat(2) объяснено почему это может
быть полезно.
Если в pathname задан относительный путь и dirfd равно специальному значению AT_FDCWD, то pathname
рассматривается относительно текущего рабочего каталога вызывающего процесса (как utimes(2)).
Если в pathname задан абсолютный путь, то dirfd игнорируется.
The flags argument is a bit mask created by ORing together zero or more of the following values defined
in <fcntl.h>:
AT_EMPTY_PATH (начиная с Linux 5.8)
Если значение pathname равно пустой строке, то выполнять действие над файлом, на который указывает
dirfd (который может быть получен с помощью open(2) с флагом O_PATH). В этом случае, dirfd может
указывать на файл любого типа, а не только на каталог. Если dirfd равно AT_FDCWD, то вызов
выполняет действие над текущим рабочим каталогом. Этот флаг есть только в Linux; для получения его
определения определите _GNU_SOURCE.
AT_SYMLINK_NOFOLLOW
Если pathname указывает на символьную ссылку, то обновляются временные метки ссылки, а не файла,
на который она ссылается.
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении utimensat() и futimens() возвращается 0. При ошибке возвращается -1, а в errno
содержится код ошибки.
ОШИБКИ
EACCES times is NULL, or both tv_nsec values are UTIME_NOW, and the effective user ID of the caller does
not match the owner of the file, the caller does not have write access to the file, and the caller
is not privileged (Linux: does not have either the CAP_FOWNER or the CAP_DAC_OVERRIDE capability).
EBADF (futimens()) Значение fd не является правильным файловым дескриптором.
EBADF (utimensat()) В pathname содержится относительный путь, но значение dirfd не равно AT_FDCWD и не
является правильным файловым дескриптором.
EFAULT Значение times указывает на некорректный адрес; или dirfd равно AT_FDCWD и pathname равно NULL или
содержит некорректный адрес.
EINVAL Некорректное значение flags.
EINVAL Invalid value in one of the tv_nsec fields (value outside range [0, 999,999,999], and not
UTIME_NOW or UTIME_OMIT); or an invalid value in one of the tv_sec fields.
EINVAL Значение pathname равно NULL, dirfd не равно AT_FDCWD и flags содержит AT_SYMLINK_NOFOLLOW.
ELOOP (utimensat()) Во время определения pathname встретилось слишком много символьных ссылок.
ENAMETOOLONG
(utimensat()) Слишком длинное значение аргумента pathname.
ENOENT (utimensat()) Компонент пути pathname не ссылается на существующий каталог или файл, или в
pathname указана пустая строка.
ENOTDIR
(utimensat()) В pathname содержится относительный путь, но значение dirfd не равно AT_FDCWD или не
является файловым дескриптором, ссылающимся на каталог; или один из компонентов pathname не
является каталогом.
EPERM Вызывающий пытается изменить одну или обе временные метки на значение, отличное от текущего
времени, или изменить одну из временных меток на текущее время, а другую оставить неизменной (т.
е., значение times не равно NULL, у обоих значений поле tv_nsec не равно UTIME_NOW, и у обоих
значений поле tv_nsec не равно UTIME_OMIT) и:
• эффективный пользовательский идентификатор не совпадает с идентификатором владельца файла, а
вызывающий не имеет привилегий (Linux: не имеет мандата CAP_FOWNER);
• файл помечен как только для добавления или как неизменяемый (см. chattr(1)).
EROFS Файл расположен в файловой системе, доступной только для чтения.
ESRCH (utimensat()) В одном из каталогов префикса pathname не разрешён поиск.
АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
┌─────────────────────────────────────────────────────────────────────┬──────────────────────┬──────────┐
│ Интерфейс │ Атрибут │ Значение │
├─────────────────────────────────────────────────────────────────────┼──────────────────────┼──────────┤
│ utimensat(), futimens() │ Безвредность в нитях │ MT-Safe │
└─────────────────────────────────────────────────────────────────────┴──────────────────────┴──────────┘
ВЕРСИИ
Отличия между библиотекой C и ABI ядра
В Linux, futimens() представляет собой библиотечную функцию на основе системного вызова utimensat(). Для
этого в Linux-версии системного вызова utimensat() реализовано нестандартное свойство: если значение
pathname равно NULL, то вызов изменяет временные метки файла на который ссылается файловый дескриптор
dirfd (который может указывать на файл любого типа). С помощью этого свойства вызов futimens(fd, times)
реализован как:
utimensat(fd, NULL, times, 0);
Однако заметим, что обёрточная функция glibc для utimensat() не позволяет передачу NULL в качестве
значения pathname — в этом случае возвращается ошибка EINVAL.
СТАНДАРТЫ
POSIX.1-2008.
ВЕРСИИ
utimensat()
Linux 2.6.22, glibc 2.6. POSIX.1-2008.
futimens()
glibc 2.6. POSIX.1-2008.
ПРИМЕЧАНИЯ
Вызов utimensat() заменяет устаревший futimesat(2).
В Linux, временные метки нельзя изменять у файлов, помеченных как неизменяемые (immutable), а у файлов,
помеченных как только для добавления, можно изменить метку только на значение текущего времени (это
соответствует сложившемуся исторически поведению в Linux вызовов utime(2) и utimes(2)).
Если оба поля tv_nsec равны UTIME_OMIT, то вызов utimensat() реализации Linux завершается без ошибки,
даже, если файл, на который ссылается dirfd и pathname, не существует.
ОШИБКИ
Several bugs afflict utimensat() and futimens() before Linux 2.6.26. These bugs are either
nonconformances with the POSIX.1 draft specification or inconsistencies with historical Linux behavior.
• В POSIX.1 определено, что если в одном из значений времени поле tv_nsec содержит значение UTIME_NOW
или UTIME_OMIT, то значение соответствующего поля tv_sec должно игнорироваться. Вместо этого
требуется, чтобы значение поля tv_sec равнялось 0 (иначе выдаётся ошибка EINVAL).
• Различные дефекты возникают при рассмотрении имеющихся прав и значений: случай, когда у обоих значений
поле tv_nsec равно UTIME_NOW, не всегда рассматривается равным указанию в times значения NULL, и
случай, когда одно значение tv_nsec равно UTIME_NOW, а другое — UTIME_OMIT, не рассматривается равным
указанию в times указателя на массив структур, содержащий произвольные значения времени. В результате
в некоторых случаях: а) временные метки файлов могут быть обновлены процессом, который не имеет прав
на это; б) временные метки файлов не могут быть обновлены процессом, хотя он имеет на это право; в) в
случае ошибки возвращается неправильное значение в errno.
• В POSIX.1 сказано, что процесс имеющий права на запись в файл, для установки временных меток в текущее
время может выполнить вызов со значением times равным NULL, или с times, указывающим на массив
структур, в котором у обоих значений времени поле tv_nsec равно UTIME_NOW. Однако futimens() вместо
этого проверяет права на запись у файлового дескриптора.
СМОТРИТЕ ТАКЖЕ
chattr(1), touch(1), futimesat(2), openat(2), stat(2), utimes(2), futimes(3), timespec(3), inode(7),
path_resolution(7), symlink(7)
ПЕРЕВОД
Русский перевод этой страницы руководства разработал(и) Azamat Hackimov <azamat.hackimov@gmail.com>,
Dmitriy Ovchinnikov <dmitriyxt5@gmail.com>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Katrin Kutepova
<blackkatelv@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 или
более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.
Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом
разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских
переводчиков.
Справочные страницы Linux 6.9.1 2 мая 2024 г. utimensat(2)