.\" -*- coding: UTF-8 -*- '\" t .\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk .\" .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH utimensat 2 "20 июля 2023 г." "Linux man\-pages 6.05.01" .SH ИМЯ utimensat, futimens \- изменение временных меток файла с наносекундной точностью .SH LIBRARY Standard C library (\fIlibc\fP, \fI\-lc\fP) .SH СИНТАКСИС .nf \fB#include \fP /* определения констант \fBAT_*\fP */ \fB#include \fP .PP \fBint utimensat(int \fP\fIdirfd\fP\fB, const char *\fP\fIpathname\fP\fB,\fP \fB const struct timespec \fP\fItimes\fP\fB[_Nullable 2], int \fP\fIflags\fP\fB);\fP \fBint futimens(int \fP\fIfd\fP\fB, const struct timespec \fP\fItimes\fP\fB[_Nullable 2]);\fP .fi .PP .RS -4 Требования макроса тестирования свойств для glibc (см. \fBfeature_test_macros\fP(7)): .RE .PP \fButimensat\fP(): .nf Начиная с glibc 2.10: _POSIX_C_SOURCE >= 200809L До glibc 2.10: _ATFILE_SOURCE .fi .PP \fBfutimens\fP(): .nf Начиная с glibc 2.10: _POSIX_C_SOURCE >= 200809L До glibc 2.10: _BSD_SOURCE .fi .SH ОПИСАНИЕ Вызовы \fButimensat\fP() и \fBfutimens\fP() обновляют временные метки файла с наносекундной точностью. Этим они отличаются от \fButime\fP(2) и \fButimes\fP(2), которые имеют секундную и микросекундную точность, соответственно. .PP В вызове \fButimensat\fP() файл задаётся в \fIpathname\fP по имени. В вызове \fBfutimens\fP() файл указывается в виде открытого файлового дескриптора в \fIfd\fP. .PP For both calls, the new file timestamps are specified in the array \fItimes\fP: \fItimes[0]\fP specifies the new "last access time" (\fIatime\fP); \fItimes[1]\fP specifies the new "last modification time" (\fImtime\fP). Each of the elements of \fItimes\fP 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 \fBtimespec\fP(3) structure. .PP Обновлённые временные метки файла устанавливаются в самое большое значение, поддерживаемое файловой системой, но не больше чем указанное время. .PP .\" 2.6.22 was broken: it is not ignored Если в поле \fItv_nsec\fP одной из структур \fItimespec\fP указано специальное значение \fBUTIME_NOW\fP, то соответствующая временная метка файла устанавливается в значение текущего времени. Если в поле \fItv_nsec\fP одной из структур \fItimespec\fP указано специальное значение \fBUTIME_OMIT\fP, то соответствующая временная метка файла не изменяется. В обоих случаях значение поля \fItv_sec\fP игнорируется. .PP .\" Если значение \fItimes\fP равно NULL, то значение обеих временных меток становится равным текущему времени. .PP The status change time (ctime) will be set to the current time, even if the other time stamps don't actually change. .SS "Права доступа" Чтобы установить временные метки файла равными текущему времени (т.е., значение \fItimes\fP равно NULL, или оба значения поля \fItv_nsec\fP равно \fBUTIME_NOW\fP) требуется одно из: .IP \[bu] 3 .\" 2.6.22 was broken here -- for futimens() the check is .\" based on whether or not the file descriptor is writable, .\" not on whether the caller's effective UID has write .\" permission for the file referred to by the descriptor. вызывающий должен иметь право на запись в файл; .IP \[bu] эффективный пользовательский идентификатор вызывающего должен совпадать с идентификатором владельца файла; .IP \[bu] вызывающий должен иметь соответствующие права. .PP .\" 2.6.22 was broken here: .\" both must be something other than *either* UTIME_OMIT *or* UTIME_NOW. Чтобы установить временные метки файла равными не текущему времени (т. е., значение \fItimes\fP не равно NULL, или оба значения поля \fItv_nsec\fP не равны \fBUTIME_NOW\fP или \fBUTIME_OMIT\fP) требуется выполнение условия 2 или 3. .PP .\" .\" Если в обоих значениях поле \fItv_nsec\fP равно \fBUTIME_OMIT\fP, то проверки владения файлом и права доступа к нему не выполняются, и временные метки файла не изменяются, но всё равно могут проверяться другие условия возникновения ошибок. .SS "Особенности utimensat()" Если в \fIpathname\fP указано относительное значение имени, то по умолчанию оно отсчитывается от каталога, на который ссылается открытый файловый дескриптор, \fIdirfd\fP (а не от текущего рабочего каталога вызывающего процесса, как это делается в \fButimes\fP(2) для относительных имён). В \fBopenat\fP(2) объяснено почему это может быть полезно. .PP Если в \fIpathname\fP задан относительный путь и \fIdirfd\fP равно специальному значению \fBAT_FDCWD\fP, то \fIpathname\fP рассматривается относительно текущего рабочего каталога вызывающего процесса (как \fButimes\fP(2)). .PP Если в \fIpathname\fP задан абсолютный путь, то \fIdirfd\fP игнорируется. .PP Значение поля \fIflags\fP представляет собой битовую маску и может равняться 0 или содержать следующую константу (определена в \fI\fP): .TP \fBAT_SYMLINK_NOFOLLOW\fP Если \fIpathname\fP указывает на символьную ссылку, то обновляются временные метки ссылки, а не файла, на который она ссылается. .SH "ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ" При успешном выполнении \fButimensat\fP() и \fBfutimens\fP() возвращается 0. При ошибке возвращается \-1, а в \fIerrno\fP содержится код ошибки. .SH ОШИБКИ .TP \fBEACCES\fP .\" But Linux 2.6.22 was broken here. .\" Traditionally, utime()/utimes() gives the error EACCES for the case .\" where the timestamp pointer argument is NULL (i.e., set both timestamps .\" to the current time), and the file is owned by a user other than the .\" effective UID of the caller, and the file is not writable by the .\" effective UID of the program. utimensat() also gives this error in the .\" same case. However, in the same circumstances, when utimensat() is .\" given a 'times' array in which both tv_nsec fields are UTIME_NOW, which .\" provides equivalent functionality to specifying 'times' as NULL, the .\" call succeeds. It should fail with the error EACCES in this case. .\" .\" POSIX.1-2008 has the following: .\" .TP .\" .B EACCES .\" .RB ( utimensat ()) .\" .I fd .\" was not opened with .\" .B O_SEARCH .\" and the permissions of the directory to which .\" .I fd .\" refers do not allow searches. .\" EXT2_IMMUTABLE_FL and similar flags for other filesystems. \fItimes\fP is NULL, or both \fItv_nsec\fP values are \fBUTIME_NOW\fP, 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 \fBCAP_FOWNER\fP or the \fBCAP_DAC_OVERRIDE\fP capability). .TP \fBEBADF\fP (\fBfutimens\fP()) Значение \fIfd\fP не является правильным файловым дескриптором. .TP \fBEBADF\fP (\fButimensat\fP()) В \fIpathname\fP содержится относительный путь, но значение \fIdirfd\fP не равно \fBAT_FDCWD\fP и не является правильным файловым дескриптором. .TP \fBEFAULT\fP Значение \fItimes\fP указывает на некорректный адрес; или \fIdirfd\fP равно \fBAT_FDCWD\fP и \fIpathname\fP равно NULL или содержит некорректный адрес. .TP \fBEINVAL\fP Некорректное значение \fIflags\fP. .TP \fBEINVAL\fP Invalid value in one of the \fItv_nsec\fP fields (value outside range [0, 999,999,999], and not \fBUTIME_NOW\fP or \fBUTIME_OMIT\fP); or an invalid value in one of the \fItv_sec\fP fields. .TP \fBEINVAL\fP .\" SUSv4 does not specify this error. Значение \fIpathname\fP равно NULL, \fIdirfd\fP не равно \fBAT_FDCWD\fP и \fIflags\fP содержит \fBAT_SYMLINK_NOFOLLOW\fP. .TP \fBELOOP\fP (\fButimensat\fP()) Во время определения \fIpathname\fP встретилось слишком много символьных ссылок. .TP \fBENAMETOOLONG\fP (\fButimensat\fP()) Слишком длинное значение аргумента \fIpathname\fP. .TP \fBENOENT\fP (\fButimensat\fP()) Компонент пути \fIpathname\fP не ссылается на существующий каталог или файл, или в \fIpathname\fP указана пустая строка. .TP \fBENOTDIR\fP (\fButimensat\fP()) В \fIpathname\fP содержится относительный путь, но значение \fIdirfd\fP не равно \fBAT_FDCWD\fP или не является файловым дескриптором, ссылающимся на каталог; или один из компонентов \fIpathname\fP не является каталогом. .TP \fBEPERM\fP Вызывающий пытается изменить одну или обе временные метки на значение, отличное от текущего времени, или изменить одну из временных меток на текущее время, а другую оставить неизменной (т. е., значение \fItimes\fP не равно NULL, у обоих значений поле \fItv_nsec\fP не равно \fBUTIME_NOW\fP, и у обоих значений поле \fItv_nsec\fP не равно \fBUTIME_OMIT\fP) и: .RS .IP \[bu] 3 эффективный пользовательский идентификатор не совпадает с идентификатором владельца файла, а вызывающий не имеет привилегий (Linux: не имеет мандата \fBCAP_FOWNER\fP); .IP \[bu] .\" Linux 2.6.22 was broken here: .\" it was not consistent with the old utimes() implementation, .\" since the case when both tv_nsec fields are UTIME_NOW, was not .\" treated like the (times == NULL) case. .\" EXT2_IMMUTABLE_FL EXT_APPEND_FL and similar flags for .\" other filesystems. .\" .\" Why the inconsistency (which is described under NOTES) between .\" EACCES and EPERM, where only EPERM tests for append-only. .\" (This was also so for the older utimes() implementation.) файл помечен как только для добавления или как неизменяемый (см. \fBchattr\fP(1)). .RE .TP \fBEROFS\fP Файл расположен в файловой системе, доступной только для чтения. .TP \fBESRCH\fP (\fButimensat\fP()) В одном из каталогов префикса \fIpathname\fP не разрешён поиск. .SH АТРИБУТЫ Описание терминов данного раздела смотрите в \fBattributes\fP(7). .TS allbox; lbx lb lb l l l. Интерфейс Атрибут Значение T{ .na .nh \fButimensat\fP(), \fBfutimens\fP() T} Безвредность в нитях MT\-Safe .TE .sp 1 .SH ВЕРСИИ .SS "Отличия между библиотекой C и ABI ядра" В Linux, \fBfutimens\fP() представляет собой библиотечную функцию на основе системного вызова \fButimensat\fP(). Для этого в Linux\-версии системного вызова \fButimensat\fP() реализовано нестандартное свойство: если значение \fIpathname\fP равно NULL, то вызов изменяет временные метки файла на который ссылается файловый дескриптор \fIdirfd\fP (который может указывать на файл любого типа). С помощью этого свойства вызов \fIfutimens(fd,\ times)\fP реализован как: .PP .in +4n .EX utimensat(fd, NULL, times, 0); .EE .in .PP Однако заметим, что обёрточная функция glibc для \fButimensat\fP() не позволяет передачу NULL в качестве значения \fIpathname\fP — в этом случае возвращается ошибка \fBEINVAL\fP. .SH СТАНДАРТЫ POSIX.1\-2008. .SH ВЕРСИИ .TP \fButimensat\fP() Linux 2.6.22, glibc 2.6. POSIX.1\-2008. .TP \fBfutimens\fP() glibc 2.6. POSIX.1\-2008. .SH ЗАМЕЧАНИЯ Вызов \fButimensat\fP() заменяет устаревший \fBfutimesat\fP(2). .PP В Linux, временные метки нельзя изменять у файлов, помеченных как неизменяемые (immutable), а у файлов, помеченных как только для добавления, можно изменить метку только на значение текущего времени (это соответствует сложившемуся исторически поведению в Linux вызовов \fButime\fP(2) и \fButimes\fP(2)). .PP Если оба поля \fItv_nsec\fP равны \fBUTIME_OMIT\fP, то вызов \fButimensat\fP() реализации Linux завершается без ошибки, даже, если файл, на который ссылается \fIdirfd\fP и \fIpathname\fP, не существует. .SH ДЕФЕКТЫ Several bugs afflict \fButimensat\fP() and \fBfutimens\fP() before Linux 2.6.26. These bugs are either nonconformances with the POSIX.1 draft specification or inconsistencies with historical Linux behavior. .IP \[bu] 3 В POSIX.1 определено, что если в одном из значений времени поле \fItv_nsec\fP содержит значение \fBUTIME_NOW\fP или \fBUTIME_OMIT\fP, то значение соответствующего поля \fItv_sec\fP должно игнорироваться. Вместо этого требуется, чтобы значение поля \fItv_sec\fP равнялось 0 (иначе выдаётся ошибка \fBEINVAL\fP). .IP \[bu] .\" Below, the long description of the errors from the previous bullet .\" point (abridged because it's too much detail for a man page). .\" .IP * .\" If one of the .\" .I tv_nsec .\" fields is .\" .BR UTIME_OMIT .\" and the other is .\" .BR UTIME_NOW , .\" then the error .\" .B EPERM .\" should occur if the process's effective user ID does not match .\" the file owner and the process is not privileged. .\" Instead, the call successfully changes one of the timestamps. .\" .IP * .\" If file is not writable by the effective user ID of the process and .\" the process's effective user ID does not match the file owner and .\" the process is not privileged, .\" and .\" .I times .\" is NULL, then the error .\" .B EACCES .\" results. .\" This error should also occur if .\" .I times .\" points to an array of structures in which both .\" .I tv_nsec .\" fields are .\" .BR UTIME_NOW . .\" Instead the call succeeds. .\" .IP * .\" If a file is marked as append-only (see .\" .BR chattr (1)), .\" then Linux traditionally .\" (i.e., .\" .BR utime (2), .\" .BR utimes (2)), .\" permits a NULL .\" .I times .\" argument to be used in order to update both timestamps to the current time. .\" For consistency, .\" .BR utimensat () .\" and .\" .BR futimens () .\" should also produce the same result when given a .\" .I times .\" argument that points to an array of structures in which both .\" .I tv_nsec .\" fields are .\" .BR UTIME_NOW . .\" Instead, the call fails with the error .\" .BR EPERM . .\" .IP * .\" If a file is marked as immutable (see .\" .BR chattr (1)), .\" then Linux traditionally .\" (i.e., .\" .BR utime (2), .\" .BR utimes (2)), .\" gives an .\" .B EACCES .\" error if .\" .I times .\" is NULL. .\" For consistency, .\" .BR utimensat () .\" and .\" .BR futimens () .\" should also produce the same result when given a .\" .I times .\" that points to an array of structures in which both .\" .I tv_nsec .\" fields are .\" .BR UTIME_NOW . .\" Instead, the call fails with the error .\" .BR EPERM . Различные дефекты возникают при рассмотрении имеющихся прав и значений: случай, когда у обоих значений поле \fItv_nsec\fP равно \fBUTIME_NOW\fP, не всегда рассматривается равным указанию в \fItimes\fP значения NULL, и случай, когда одно значение \fItv_nsec\fP равно \fBUTIME_NOW\fP, а другое — \fBUTIME_OMIT\fP, не рассматривается равным указанию в \fItimes\fP указателя на массив структур, содержащий произвольные значения времени. В результате в некоторых случаях: а) временные метки файлов могут быть обновлены процессом, который не имеет прав на это; б) временные метки файлов не могут быть обновлены процессом, хотя он имеет на это право; в) в случае ошибки возвращается неправильное значение в \fIerrno\fP. .IP \[bu] .\" This means that a process with a file descriptor that allows .\" writing could change the timestamps of a file for which it .\" does not have write permission; .\" conversely, a process with a read-only file descriptor won't .\" be able to update the timestamps of a file, .\" even if it has write permission on the file. В POSIX.1 сказано, что процесс имеющий \fIправа на запись в файл\fP, для установки временных меток в текущее время может выполнить вызов со значением \fItimes\fP равным NULL, или с \fItimes\fP, указывающим на массив структур, в котором у обоих значений времени поле \fItv_nsec\fP равно \fBUTIME_NOW\fP. Однако \fBfutimens\fP() вместо этого проверяет \fIправа на запись у файлового дескриптора\fP. .SH "СМ. ТАКЖЕ" \fBchattr\fP(1), \fBtouch\fP(1), \fBfutimesat\fP(2), \fBopenat\fP(2), \fBstat\fP(2), \fButimes\fP(2), \fBfutimes\fP(3), \fBtimespec\fP(3), \fBinode\fP(7), \fBpath_resolution\fP(7), \fBsymlink\fP(7) .PP .SH ПЕРЕВОД Русский перевод этой страницы руководства был сделан Azamat Hackimov , Dmitriy Ovchinnikov , Dmitry Bolkhovskikh , Katrin Kutepova , Yuri Kozlov и Иван Павлов . .PP Этот перевод является бесплатной документацией; прочитайте .UR https://www.gnu.org/licenses/gpl-3.0.html Стандартную общественную лицензию GNU версии 3 .UE или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ. .PP Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на .MT man-pages-ru-talks@lists.sourceforge.net .ME .