utime() - Unix 和 Linux 系统调用

名称

utime、utimes - 更改 inode 的访问和/或修改时间

语法

#include <sys/types.h> 
#include <utime.h> 

int utime(const char *filename, const struct utimbuf *buf); 

#include <sys/time.h> 

int utimes(const char *filename, const struct timeval times[2]);

描述

utime() 将由 filename 指定的 inode 的访问和修改时间分别更改为 buf 的 actime 和 modtime 字段。

如果 buf 为 NULL，则将文件的时间戳设置为当前时间。

在以下情况下允许更改时间戳：进程具有相应的权限（Linux：具有 CAP_FOWNER 功能），或者有效用户 ID 等于文件的所有者 ID，或者 buf 必须为 NULL 并且进程对文件具有写权限。

utimbuf 结构如下所示：

struct utimbuf {
    time_t actime;       /* access time */
    time_t modtime;      /* modification time */
};

函数 utime() 允许以 1 秒的分辨率指定时间戳。函数 utimes() 类似，但允许以 1 微秒的分辨率指定时间戳。此处 times[0] 指访问时间，times[1] 指修改时间。

timeval 结构如下所示：

struct timeval {
    long tv_sec;        /* seconds */
    long tv_usec;       /* microseconds */
};

返回值

成功时，返回 0。错误时，返回 -1，并且 errno 被适当地设置。

错误

标签	描述
EACCES	path 前缀中的某个目录的搜索权限被拒绝（另请参见 path_resolution(2)），或者 buf 为 NULL 并且进程没有权限更改时间戳（请参见上文）。
ENOENT	filename 不存在。
EPERM	buf 不为 NULL 并且进程没有权限更改时间戳。
EROFS	path 位于只读文件系统上。

备注

Linux 不允许更改不可变文件的时间戳，也不允许将时间戳设置为追加文件以外的其他时间。

在 libc4 和 libc5 中，utimes() 只是 utime() 的包装器，因此不允许亚秒级分辨率。

POSIX.1-2001 将 utimes() 标记为传统功能，这很奇怪，因为它提供了比 utime() 更多的功能。

缺陷

Linux 没有仔细区分 EACCES 和 EPERM 错误返回。另一方面，POSIX.1-2001 在其 utimes() 错误描述中存在缺陷。

符合标准

utime()：SVr4、POSIX.1-2001。

utimes()：4.3BSD

参见

打印页面