Linux程序员手册 第2部分
更新日期： 2020-06-09

名称

utimensat，futimens-以纳秒级精度更改文件时间戳

语法

#include <fcntl.h>           /* Definition of AT_* constants */
#include <sys/stat.h>

int utimensat(int dirfd, const char *pathname,
              const struct timespec times[2], int flags);

int futimens(int fd, const struct timespec times[2]);

glibc的功能测试宏要求(请参阅feature_test_macros(7))：

utimensat()：

Since glibc 2.10:

_POSIX_C_SOURCE>= 200809L

Before glibc 2.10:

_ATFILE_SOURCE

futimens()：

Since glibc 2.10:

_POSIX_C_SOURCE>= 200809L

Before glibc 2.10:

_GNU_SOURCE

说明

utimensat()和futimens()以纳秒级精度更新文件的时间戳。这与历史性的utime(2)和utimes(2)形成对比，后者在设置文件时间戳时分别仅允许秒和微秒的精度。

使用utimensat()可以通过路径名中指定的路径名​​指定文件。使用futimens()，可以通过打开的文件描述符fd指定要更新其时间戳的文件。

对于这两个调用，新文件的时间戳记均在数组时间中指定：times [0]指定新的"上次访问时间"(atime)； times [1]指定新的"上次修改时间"(mtime)。时间的每个元素都将时间指定为自1970年1月1日00:00:00 +0000(UTC)以来的秒数和纳秒数。此信息以以下形式的结构传递：

struct timespec {
    time_t tv_sec;        /* seconds */
    long   tv_nsec;       /* nanoseconds */
};

更新的文件时间戳记设置为文件系统支持的最大值，该最大值不大于指定的时间。

如果时间规范结构之一的tv_nsec字段具有特殊值UTIME_NOW，则将相应的文件时间戳记设置为当前时间。如果时间规范结构之一的tv_nsec字段具有特殊值UTIME_OMIT，则相应的文件时间戳保持不变。在这两种情况下，都会忽略相应的tv_sec字段的值。

如果times为NULL，则两个时间戳都设置为当前时间。

Permissions requirements

要将两个文件时间戳都设置为当前时间(即，times为NULL，或者两个tv_nsec字段都指定UTIME_NOW)，请执行以下操作：

1.

调用者必须对该文件具有写访问权限；

2.

呼叫者的有效用户ID必须与文件所有者匹配；要么

3.

呼叫者必须具有适当的特权。

除了将两个时间戳都设置为当前时间以外(即times不为NULL，并且tv_nsec字段都不为UTIME_NOW并且tv_nsec字段都不为UTIME_OMIT)，要进行其他更改，必须满足上述条件2或3。

如果将两个tv_nsec字段都指定为UTIME_OMIT，则不会执行文件所有权或权限检查，并且不会修改文件时间戳，但是仍可能检测到其他错误情况。

utimensat() specifics

如果路径名是相对的，则默认情况下它是相对于打开文件描述符dirfd所引用的目录解释的(而不是相对于调用进程的当前工作目录，如utimes(2)对相对路径名所做的那样) )。请参阅openat(2)，以获取有关为什么这样做有用的解释。

如果路径名是相对的并且dirfd是特殊值AT_FDCWD，则路径名将相对于调用进程的当前工作目录进行解释(如utimes(2))。

如果路径名是绝对的，则dirfd被忽略。

标志字段是一个位掩码，可以为0，或包含以下常量，定义如下：

AT_SYMLINK_NOFOLLOW

如果路径名指定了符号链接，则更新该链接的时间戳，而不是它所引用的文件。

返回值

成功时，utimensat()和futimens()返回0。错误时，返回-1并设置errno以指示错误。

错误说明

EACCES

times为NULL或两个tv_nsec值均为UTIME_NOW，并且调用者的有效用户ID与文件的所有者不匹配，调用者没有对该文件的写访问权，并且该调用者没有特权(Linux：没有)具有CAP_FOWNER或CAP_DAC_OVERRIDE功能)。

EBADF

(futimens())fd不是有效的文件描述符。

EBADF

(utimensat())路径名是相对路径名，但dirfd既不是AT_FDCWD也不是有效的文件描述符。

EFAULT

指向无效地址的时间；或者，dirfd是AT_FDCWD，并且路径名是NULL或无效的地址。

EINVAL

标志中的值无效。

EINVAL

tv_nsec字段之一中的值无效(值在0到999,999,999范围之外，并且不是UTIME_NOW或UTIME_OMIT)；或tv_sec字段之一中的值无效。

EINVAL

路径名是NULL，dirfd不是AT_FDCWD，并且标志包含AT_SYMLINK_NOFOLLOW。

ELOOP

(utimensat())解析路径名时遇到太多符号链接。

ENAMETOOLONG

(utimensat())路径名太长。

ENOENT

(utimensat())路径名的组件未引用现有目录或文件，或者路径名是空字符串。

ENOTDIR

(utimensat())路径名是相对路径名，但dirfd既不是AT_FDCWD也不是引用目录的文件描述符；或者，路径名的前缀组成部分之一不是目录。

EPERM

The caller attempted to change one or both timestamps to a value other than the current time, or to change one of the timestamps to the current time while leaving the other timestamp unchanged, (i.e., times

is not NULL, neither
tv_nsec

field is
UTIME_NOW,

and neither
tv_nsec

field is
UTIME_OMIT)

and either:

*

调用者的有效用户ID与文件的所有者不匹配，并且调用者没有特权(Linux：不具有CAP_FOWNER功能)；要么，

*

该文件被标记为仅追加或不可变(请参见chattr(1))。

EROFS

该文件位于只读文件系统上。

ESRCH

(utimensat())拒绝对路径名的前缀组件之一进行搜索。

版本

utimensat()在内核2.6.22中添加到Linux； glibc支持是在2.6版中添加的。

对futimens()的支持最早出现在glibc 2.6中。

属性

有关本节中使用的术语的说明，请参见attribute(7)。

遵循规范

futimens()和utimensat()在POSIX.1-2008中指定。

备注

utimensat()已过时futimesat(2)。

在Linux上，不能更改标记为不可变的文件的时间戳，标记为append-only的文件唯一允许的更改是将时间戳设置为当前时间。 (这与utime(2)和utimes(2)在Linux上的历史行为一致。)

如果将两个tv_nsec字段都指定为UTIME_OMIT，则即使dirfd和路径名引用的文件不存在，utimensat()的Linux实现也会成功。

C library/kernel ABI differences

在Linux上，futimens()是在utimensat()系统调用之上实现的库函数。为此，Linux utimensat()系统调用实现了非标准功能：如果路径名为NULL，则该调用将修改文件描述符dirfd引用的文件的时间戳(该文件描述符可以引用任何类型的文件)。使用此功能，调用futimens(fd，times)实现为：

utimensat(fd, NULL, times, 0);

但是请注意，用于utimensat()的glibc包装器不允许传递NULL作为路径名的值：在这种情况下，包装器函数返回错误EINVAL。

BUGS

在2.6.26之前的内核中，一些错误困扰utimensat()和futimens()。这些错误要么是与POSIX.1草案规范不符，要么是与Linux的历史行为不符。

*

POSIX.1指定如果tv_nsec字段之一的值为UTIME_NOW或UTIME_OMIT，则应忽略相应tv_sec字段的值。而是，tv_sec字段的值必须为0(或错误EINVAL结果)。

*

各种错误意味着，出于权限检查的目的，两个tv_nsec字段都设置为UTIME_NOW的情况并不总是与将时间指定为NULL的情况相同，而一个tv_nsec值为UTIME_NOW且另一个值为UTIME_OMIT的情况则不是"与将时间指定为指向包含任意时间值的结构数组的指针一样。结果，在某些情况下：a)文件时间戳可以由不具有执行更新权限的进程来更新； b)文件时间戳不能由具有执行更新权限的进程更新； c)发生错误时返回错误的errno值。

*

POSIX.1说，具有对文件写访问权限的进程可以使用NULL或带有指向两个tv_nsec字段均为UTIME_NOW的结构数组的时间进行调用，以便将两个时间戳都更新为当前时间。 。但是，futimens()会检查文件描述符的访问模式是否允许写入。

另外参见

chattr(1)，touch(1)，futimesat(2)，openat(2)，stat(2)，utimes(2)，futimes(3)，inode(7)，path_resolution(7)，symlink(7)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。